Markdown is a markup language.
Its advantage over HTML is that it allows to format text while keeping the text readable as plain text. It is more easibly readible and writable compered to other markup languages.
On the other hand, it is more human-oriented than computer-oriented so it cannot be parsed as easily as other more structured languages.
Markdown flavors
Markdown flavors:
- John Gruber’s Markdown
- Pandoc Markdown
- Quarto Markdown
- CommonMark
- MyST markdown
- commonmark_x
John Gruber's Mardown (2004)
├─ Pandoc Markdown (2006)
│ ├─ Quarto Markdown
├─ CommonMark (2014)
├─ MyST-commonmark
├─ GFM
├─ commonmark_x (2020)John Gruber’s Markdown
John Gruber’s Markdown is an extension of Markdown aimed to document generation and publishing.
It was released by John Gruber and Aaron Schwartz in 2004 to have a markup language that was easy to read. There was no specification but just a script to convert from Markdown to HTML.
John Gruber’s Markdown website
CommonMark
CommonMark is a markup language based Markdown that formalize its specification. You can read more in the CommonMark official website.
It was released in 2014 with the goal of removing the ambiguities of John Gruber’s Markdown.
MyST markdown
Markedly Structured Text (MyST) markdown is an extension of CommonMark that adds additional featured available on the ReStructuredText (RST) markup language.
The MyST-parser is an add-on for the Sphinx document generator that allows to read MyST-markdown (instead of its native RST) and process it to generate documentation.
MyST markdown official website
Pandoc Markdown
Pandoc Markdown is an extended and slightly modified version of John Gruber’s Markdown.
Pandoc can convert documents written in Pandoc Markdown to multiple document formats. You can read more on this external link.
Quarto Markdown
Quarto Markdown is an extension on Pandoc Markdown. It is the one used in Quarto publishing system.
GFM
GitHub Flavored Markdown (GFM) is a Markdown flavor based on CommonMark that adds tables, task lists, strikethroughs, formulas or Mermaid code diagrams.
It is used on GitHub and Jupyter.
commonmark_x
commonmark_x is a Markdown flavor that tries to combine the standardization of CommonMark standard with the additions of Pandoc and Quarto Markdown flavors. Its goal is to be Commonmark compliant and be compatible with third-parties while extending Pandoc+Quarto functionalities that doesn’t violate Commonmark rules.
Nevertheless, there are some current Pandoc markdown features (like citations) that are not available on commonmark_x.
It was released in July 2020 with the rollout of Pandoc 2.10.
It is supported by Pandoc and Quarto.
commonmark_x vs Quarto Markdown comparison
Markdown Tools
Markdown Editors
Markdown editors featured on this post:
- Marktext
- Obsidian
- Typora
- Visual Studio Code
- Notepad++
- Project Jupyter
Marktext
Marktext is FOSS.
Obsidian
Obsidian is one of the most popular markdown editors. It has preview or WYSIWYG capabilities.
Obsidian is proprietary software.
Typora
Typora is a desktop application.
StackEdit
StackEdit is an online editor for Markup language.
Visual Studio Code
Visual Studio Code contains extension for markdown file edition.
One of the most popular extensions for this purpose is markdownlint.
markdownlint at Visual Studio Marketplace
Project Jupyter
You can use the Project Jupyter software to generate markdown.
You can export it to PDF from the GUI.
Markdown parser
Markdown parser:
- Goldmark
- markdown-it-py
Goldmark
Goldmark is a FOSS markdown parser based compliant with CommonMark extension.
markdown-it-py
markdown-it-py is a Markdown parser for Python.
It is used by the MyST-parser extension of Sphinx.
Markdown document generators
Markdown document generator types:
- Document converter
- Documentation generator
- Static publishing system
- Publishing system
Markdown document converter
There are tools to convert Markdown documents to other formats like DOCX, PDF or EPUB.
- Pandoc
Pandoc with Markdown
Pandoc is able to work with Markdown.
Example:
# Markdown + LaTex to PDF Test using Pandoc
## The actual test
This is a **test** of a *Markdown* file that includes LaTeX formulas and that can be generated as a PDF file.
This is an inline LaTex formula, $E=mc^2$, as you may see.
This is a new line LateX formula:
$\frac{-b \pm \sqrt{b^2 -4ac}}{2a}$
I hope that it works fine.
## Reading this test a PDF
You can run convert a Markdown file containing this code into PDF by typing this on a shell:
```shell
pandoc test.md -o test.pdf
```
You need to have Pandoc installed in your system.You can find a project template to create a book with Markdown and Pandoc on this external link.
It also supports commonmark_x with pandoc -t commonmark_x for reading and pandoc -t commonmark_x for writing.
Markdown documentation generator
Examples are:
- Sphinx
Sphinx with Markdown
Sphinx is a documentation generator that creates HTML websites , but it can also be used to create PDFs through LaTeX.
You can read this post about Sphinx.
You can find a project template to create a book with Markdown and Sphinx on this external link.
Markdown static document generator
A Markdown static document generator (SDG) generates a website from Markdown code.
Examples are:
- MkDocs
- Hugo
You can have a look at generic markup-to-doc tools, also called static document generator.
Markdown publishing systems
Quarto with Markdown
Quarto includes tools for document conversion.
Markdown Syntax
Referring to a section within the same document
There are basically two ways:
- Title
- Other sections
Referring to a title within the same document
Markdown creates an anchorage to a title within the document.
[click on this link](#my-multi-word-header)
### My Multi Word HeaderReferring to a section different to a title within the same document
You need to use HTML in this case.
[click on this link](#reference)
<a id="reference">Text</a>The use of attribute “name” instead of “id” comes from older HTML versions, but its use is now deprecated.
You might also be interested in…
External References
- Reddit community; “Markdown editor with WYSIWYG for basic note taking“; Reddit
- Referring to a section within the same document
- Eddimens; “Jumping To Any Section Of Your Markdown Document“; Eddimens
- Stackoverflow; “How to link to part of the same document in Markdown?“; Stackoverflow