Markup languages
you know and like
Choose your favorite syntax for creating documentation. Markdown for its simplicity and popularity, or reStructuredText for its advanced features and flexibility.
What is markup language?
Which one to choose?
Markup languages like Markdown and reStructuredText are preferred over WYSIWYG editors for several reasons. Markup languages offer more control and flexibility for documentation and collaborative projects.
- Plain text - Markup files are plain text, making them easy to write and read. Plain text are also good easily versioned.
- Portability - Markup ensures consistent formatting across different tools and applications which support it. For example, Google Docs and Documatt can render the same markup syntax.
- Automation - Markup can be easily processed, converted, or rendered into various formats (HTML, PDF, etc.) using scripts or static site generators like Documatt.
- Focus - Writing in markup reduces distractions from formatting options, letting you focus on content.
Why choose Markdown?
For those prioritizing simplicity and ease of use, Markdown often emerges as the clear winner. Its gentle learning curve and widespread adoption make it an attractive option for a variety of applications.
- Effortless Simplicity - Its clean, intuitive syntax is easy to learn and read.
- Huge Ecosystem - It's the standard on platforms like GitHub and Google Docs, with vast tool support.
- Easy Collaboration - Simple enough for anyone to contribute without special training.
- Ideal for Simpler Content - Perfect for READMEs, blog posts, and basic documents.
- Flexible "Flavors" - Extensions like GFM add features like tables when needed.
Reason to choose reStructuredText
For projects that demand more power, structure, and extensibility, especially in the realm of technical documentation, reStructuredText stands out as the more robust choice.
- Powerful Built-in Features - Natively supports tables, footnotes, and other complex elements.
- Highly Extensible - Use "directives" to create custom elements like auto-generated content.
- Semantic and Structured - Defines the logical structure of a document, not just its look.
- A Single Standard - Ensures consistent rendering across all tools and platforms.