↓Skip to main content

Modern Markdown

·2 mins
Table of Contents

Markdown has become the standard syntax for formatted text. Use Markdown documents for any kind of written content. For example, input and output for LLMs defaults to Markdown.

Many products render Markdown into other formats, such as HTML. Jupyter notebooks for interactive computation and static Website generators like Hugo and Zensical use Markdown as the source format for content.

Modern text editors for code also support Markdown. Current versions of the LibreOffice office suite now support Markdown as a document format.

Structured data formats like JSON can include Markdown documents as strings, since Markdown uses plain-text. This means that any modern data storage system will store Markdown documents.

The Markdown format supports extensions and embedded elements. You can embed metadata as frontmatter, MDX components and Mermaid diagrams into Markdown documents, as well as links to assets like images.

Dialects of Markdown #

All Markdown files use the file extension .md. There is no automatic means of distinguishing between stored CommonMark, GFM and Python Markdown documents. Content in the CommonMark format may be served with the variant MIME type text/markdown; variant=CommonMark.

Known Issues with Markdown #

  • The CommonMark standard does not specify tables and other important elements. This means that many Markdown documents use GFM syntax.
  • Tools that assume that Markdown documents use CommonMark and GFM syntax may fail on Python Markdown documents.
  • Content from humans often contain formatting errors.
  • Internal and external links may be invalid or broken. Use rumdl to check internal and anchor links, and a tool such as lychee to check the links to external sites.

Use rumdl to lint and format Markdown files. It supports the popular variations of Markdown, including CommonMark, GFM and Python Markdown.