Documentation FundamentalsLesson 1.4

Setting up a docs-as-code workflow with Markdown

Markdown syntax, docs-as-code principles, version control for docs, pull request review for docs, static site generators, file organization

Docs-as-Code with Markdown

Docs-as-code means your documentation lives in the same repository as your code, follows the same review process, and deploys automatically. Markdown is the standard format — lightweight, readable as plain text, and renderable everywhere.

Essential Markdown for Docs

# H1 — Page title (use once)
## H2 — Major section
### H3 — Sub-section

**bold** for UI labels and key terms
`inline code` for commands, file paths, variable names

```bash
# Code blocks for all runnable code
npm install my-package
```

> Callout for warnings or important notes

- Unordered list for non-sequential items
1. Ordered list for sequential steps

File Organization

Use a predictable structure:

docs/
  getting-started.md
  api-reference/
    authentication.md
    endpoints.md
  guides/
    deployment.md
  CONTRIBUTING.md

Review Docs Like Code

Every documentation change should go through a pull request. Reviewers check: accuracy, clarity, completeness, and audience fit. Approving broken docs has the same cost as approving broken code — it just shows up differently.