Documentation

Markup

Markdown (opens in a new tab) is a lightweight markup language for creating formatted text using a plain-text editor. Files written in Markdown are not locked to the applications used to create them, as it follows the file over app (opens in a new tab)¹ philosophy.

Markdown can be used to author websites, reports, articles, notes, books, assignments, decks, slides; to write email messages; and for online discussions and documentation. It comes in multiple flavors, of which the most popular are:

1. CommonMark (opens in a new tab): A strongly defined, highly compatible specification of Markdown.
2. GFM (opens in a new tab): GitHub-Flavored Markdown, a superset of CommonMark, supported by GitHub and MDX (opens in a new tab). It can be processed using MDX (opens in a new tab), remark (opens in a new tab), and rehype (opens in a new tab) by unified (opens in a new tab).

Markdown is not the only lightweight markup language but it is the one with the better support across platforms. There are alternatives such as Asciidoctor (opens in a new tab) + Antora (opens in a new tab) and reStructuredText (opens in a new tab) + Sphinx (opens in a new tab). There are also hosted documentation platforms such as GitBook (opens in a new tab) and Read the Docs (opens in a new tab).

Pandoc

Pandoc (opens in a new tab) is a swiss-army knife for markup languages. It can convert Markdown files to a large number of formats, including, but not limited to, $\LaTeX$ (opens in a new tab), HTML (opens in a new tab), PDF (opens in a new tab), ePUB (opens in a new tab), AsciiDoc (opens in a new tab), reStructuredText (opens in a new tab), OpenDocument (opens in a new tab), and OOXML (opens in a new tab).

Pages

pandoc page.md -t html -o page.html

Documents

pandoc doc.md -t pdf -o doc.pdf
pandoc doc.md -t latex --include-in-header preamble.tex --pdf-engine=lualatex -o doc.pdf

pandoc doc.md -t docx -o doc.docx
pandoc doc.md -t docx --reference-doc=template.docx -o doc.docx

Slides

pandoc deck.md -s -t revealjs -o deck.html
pandoc deck.md -t beamer -o deck.pdf

pandoc deck.md -t pptx -o deck.pptx
pandoc deck.md -t pptx --reference-doc=template.pptx -o deck.pptx

Obsidian

Obsidian (opens in a new tab) is a personal knowledge base and note-taking software application that operates on Markdown files. It allows users to make internal links for notes and then to visualize the connections as a graph. It is designed to help users organize and structure their thoughts and knowledge in a flexible non-linear way.

Diagrams

Mermaid

Mermaid (opens in a new tab) is a diagramming and charting tool that uses text definitions and a renderer to create and modify complex diagrams. Its main purpose is to help documentation catch up with development. Mermaid code blocks can be used to embed different types of diagrams. Here is an example of a state diagram:

stateDiagram-v2
direction LR
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]

Excalidraw

Excalidraw (opens in a new tab) is a virtual collaborative whiteboard tool that lets you easily sketch diagrams that have a hand-drawn feel to them. It is available as a plugin for seamless integration with Obsidian.

Resources

• Markdown Tutorial (opens in a new tab)
• Pandoc Markdown (opens in a new tab)
• Writing on GitHub (opens in a new tab)
  • Basic writing and formatting syntax (opens in a new tab)
• MarkdownHere Cheatsheet (opens in a new tab)
• Markdown Guide (opens in a new tab)
  • Markdown Cheat Sheet (opens in a new tab)
• Awesome Markdown (opens in a new tab)
• Pandoc-Themes (opens in a new tab)
• Customizing Pandoc to generate beautiful PDF and ePub from Markdown (opens in a new tab)
• Generating a nice-looking PDF with Pandoc (opens in a new tab)
• Draw Diagrams with Markdown (opens in a new tab)
• Online text to diagram tools (opens in a new tab)
• From text to models (opens in a new tab)