Documentation

Follow this tutorial (opens in a new tab) for a quick introduction to Markdown.

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:

CommonMark (opens in a new tab): A strongly defined, highly compatible specification of Markdown.
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.

Editors

Generators

Hosting

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 --> [*]

PlantUML

PlantUML (opens in a new tab) is a highly versatile tool that facilitates the rapid and straightforward creation of a wide array of diagrams. It utilizes a simple and intuitive language that allows users to effortlessly draft various types of diagrams. PlantUML diagrams can be converted to SVG documents and linked to from Markdown documents. It provides an online (opens in a new tab) interactive diagram editor as well. Here are examples of class and sequence diagrams:

class.pu

@startuml
 
abstract class AbstractList
abstract AbstractCollection
interface List
interface Collection
 
List <|-- AbstractList
Collection <|-- AbstractCollection
 
Collection <|- List
AbstractCollection <|- AbstractList
AbstractList <|-- ArrayList
 
class ArrayList {
  -Object[] elementData
  +size() : integer
}
 
enum TimeUnit {
  DAYS
  HOURS
  MINUTES
}
 
@enduml

sequence.pu

@startuml
 
participant Participant as Foo
actor       Actor       as Foo1
boundary    Boundary    as Foo2
control     Control     as Foo3
entity      Entity      as Foo4
database    Database    as Foo5
collections Collections as Foo6
queue       Queue       as Foo7
Foo -> Foo1 : To actor
Foo -> Foo2 : To boundary
Foo -> Foo3 : To control
Foo -> Foo4 : To entity
Foo -> Foo5 : To database
Foo -> Foo6 : To collections
Foo -> Foo7 : To queue
 
@enduml

D2

D2 (opens in a new tab) is a modern DSL that turns text to diagrams. D2 diagrams can be converted to SVG documents and linked to from Markdown documents. Here is an example of a network diagram:

network.d2

vars: {
  d2-config: {
    layout-engine: elk
    # Terminal theme code
    theme-id: 300
  }
}
network: {
  cell tower: {
    satellites: {
      shape: stored_data
      style.multiple: true
    }
 
    transmitter
 
    satellites -> transmitter: send
    satellites -> transmitter: send
    satellites -> transmitter: send
  }
 
  online portal: {
    ui: {shape: hexagon}
  }
 
  data processor: {
    storage: {
      shape: cylinder
      style.multiple: true
    }
  }
 
  cell tower.transmitter -> data processor.storage: phone logs
}
 
user: {
  shape: person
  width: 130
}
 
user -> network.cell tower: make call
user -> network.online portal.ui: access {
  style.stroke-dash: 3
}
 
api server -> network.online portal.ui: display
api server -> logs: persist
logs: {shape: page; style.multiple: true}
 
network.data processor -> api server

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.

ZenUML

ZenUML (opens in a new tab) is a diagramming tool that renders text definitions to create and modify sequence diagrams dynamically.

Resources

Love letter to Obsidian (opens in a new tab) ↩

Guides 2 Version Control