general documentation

Markdown

markdown documentation plain-text git writing
Plain English

Markdown is a simple way to add formatting to plain text. You type a # for a heading, a dash for a bullet point, and wrap words in asterisks for bold. The file stays readable as plain text, but tools like GitHub turn it into a clean, formatted page. It is the standard format for README files, technical notes, and documentation.

Technical Definition

Markdown was created by John Gruber in 2004. Because the original description was loose, CommonMark defines a precise specification, and GitHub Flavored Markdown (GFM) extends it with tables, task lists, strikethrough, and autolinks.

Core syntax:

  • Headings: #, ##, ###
  • Emphasis: *italic*, **bold**
  • Lists: - or 1.; task lists - [ ] and - [x] (GFM)
  • Links: [text](https://example.com); images ![alt](path.png)
  • Inline code with single backticks; fenced code blocks with three backticks and a language name for highlighting
  • Blockquotes: >
  • Tables (GFM): pipes and a |---| separator row

Why it fits IT work:

  • Plain text diffs cleanly in Git, so changes to docs are reviewable
  • Renders automatically on GitHub, GitLab, and most wikis
  • Converts to HTML, PDF, or Word with pandoc
  • Static site generators (Astro, Hugo, MkDocs) build websites from it

MDX extends Markdown with JSX components; this dictionary is written in MDX.

Source: CommonMark specification

Markdown for an install log 

$ mkdir -p ~/notes && cd ~/notes && git init
$ cat > install-log.md << 'EOF'
# Ubuntu 26.04 VM install log

## Settings
| Item | Value |
|------|-------|
| RAM  | 4096 MB |
| Disk | 25 GB |

## Checklist
- [x] Verified ISO checksum
- [ ] Took snapshot "clean-install"
EOF

# Convert to HTML or PDF
$ sudo apt install pandoc
$ pandoc install-log.md -o install-log.html
In the Wild

Markdown is the default format for technical writing: READMEs, runbooks, incident notes, change logs, and wikis. Keeping your lab notes in Markdown inside a Git repo, as the BNLC path does from Phase 1, gives you searchable, versioned documentation and a portfolio to show employers. When a team runbook lives as Markdown next to the code, it gets updated in the same pull request as the change it describes.

← Back to Dictionary