Table of Contents

Documentation, Naming & Markdown Standards¶

The conventions that keep this repo consistent and navigable.

Folder & file naming¶

Directories: lower-case, hyphenated — cheatsheets/, month-01/, 01-cli-todo/.
Day notes: journal/month-NN/day-NNN.md (zero-padded: day-007.md).
Reviews: journal/month-NN/week-N-review.md, journal/month-NN/month-NN-review.md.
Projects: projects/NN-kebab-name/ with a SPEC.md and a README.md.
ADRs: docs/adr/NNNN-kebab-title.md (e.g. 0001-record-architecture-decisions.md).
Go files: lower-case, no underscores except _test.go; package name = directory name.
Top-level docs: UPPER_SNAKE.md (README, ROADMAP, PROGRESS, …); sub-docs may be Title-Case or kebab.

Markdown standards¶

Exactly one H1 (#) per file, as the title.
Long docs (>2 screens) start with a Table of Contents.
Use relative links between repo files so they work on GitHub and offline.
Fenced code blocks always specify a language: ```go, ```bash, ```mermaid.
Use tables for comparisons, > block-quotes for callouts, and task lists - [ ] for checklists.
Hidden answers / long examples use <details><summary>…</summary>…</details>.
Every directory has a README.md that indexes its contents.
End navigational docs with a footer linking back to the README.
Keep lines readable; MD013 (line length) is disabled in .markdownlint.json — wrap by sentence, not by column.

Diagrams¶

Prefer mermaid (renders on GitHub) for architecture, sequence, ER, and flow diagrams.
Static images go in assets/img/ with descriptive names; always set alt text.

Linking & knowledge graph¶

Cross-link concepts with [[note-name]]-style references in NOTES.md and journal notes.
Link day notes ↔ examples ↔ exercises ↔ cheatsheets so the reader can traverse.

Frontmatter¶

Day/weekly/monthly notes use YAML frontmatter (see templates/) so metadata (day, date, confidence, time) can later be parsed by scripts for progress stats.

Tone¶

Write notes for a future beginner (including future-you). Explain the why.
Be honest about mistakes and gaps — that's the most useful content.

⬅ README · CONTRIBUTING