asciidoc markdown reStructuredText mdx formats - ghdrako/doc_snipets GitHub Wiki

Markdown

• https://github.github.com/gfm/
• https://leanpub.com/lfm/read
• https://commonmark.org/

Markdown is not regulated and maintained by a standards committee, so the different versions or flavors are inconsistent. Markdown was created by John Gruber with the goal of simplifying HTML, and while others adopted and adjusted it to best fit their needs, slightly different versions of the standard called “flavors” were created like GitHub Flavored Markdown1, Leanpub Flavoured Markdown2, or CommonMark3. CommonMark is a standardized specification of the Markdown syntax, aiming to provide a more consistent and unambiguous definition of Markdown compared to the various versions that exist.

AsciiDoc and reStructuredText are two markup languages besides Markdown that are often discussed in relation to documentation. They both provide more semantic richness and are based on standards, so they can be used more consistently. GitHub supports both, and you can find many static site generators that support them, like Asciidoctor or Sphinx.

AsciiDoc

• https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/
• https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/

reStructuredText

• https://docutils.sourceforge.io/rst.html

MDX4 format and tools like Docusaurus5

• https://mdxjs.com/
• https://docusaurus.io/

MDX combines Markdown's simplicity with JSX's (a syntax extension to JavaScript) interactive capabilities, allowing the use of React components within Markdown files for advanced features. Docusaurus is an open source tool for creating documentation websites that integrates with MDX, offering dynamic content within Markdown files.