How to Use This Vault¶

The whole point of this vault is to stop forgetting what you learn. Read this once — it'll save you hours later.

The daily workflow¶

1. Pick the next topic¶

Open the sidebar and pick a topic with status 📋 Todo (or pick the next gap in one already in progress).

2. Gather your sources for that topic¶

You need at least two of these (more is better):

📺 YouTube playlist or video(s) — the teacher who explains it best for you.
📖 Official documentation URL — the source of truth.
🐙 A reference GitHub repo — real code that uses the thing.
📝 Optional: blog posts, your own scratch notes.

Drop all the links into a single message and send to Claude (or paste into your text editor and start writing yourself).

3. Watch, read, experiment¶

Don't skip this step. Notes you write without actually trying the code are notes you'll never trust. Run the examples, break them, see what happens.

4. Write the note(s)¶

For each subtopic, create a new file under docs/<topic>/:

docs/fastapi/04-dependency-injection.md

Copy the structure from NOTE_TEMPLATE.md — every section, in order. No skipping sections. If a section truly doesn't apply, write "N/A — reason" instead of deleting it.

Open mkdocs.yml at the repo root and add the new page under its topic in the nav: block:

nav:
  - FastAPI:
      - Overview: fastapi/index.md
      - Getting Started: fastapi/01-getting-started.md
      - Routing: fastapi/02-routing.md
      - Dependency Injection: fastapi/04-dependency-injection.md   # ← new
      - Sources: fastapi/sources.md

6. Log the sources¶

Open docs/<topic>/sources.md and add every link you consumed, with status:

- 📺 [FastAPI Crash Course](https://youtube.com/...) — ✅ watched, took notes
- 📖 [Official FastAPI docs](https://fastapi.tiangolo.com/) — 🚧 reading
- 🐙 [tiangolo/full-stack-fastapi-template](https://github.com/tiangolo/full-stack-fastapi-template) — 📋 to explore

7. Preview locally¶

mkdocs serve

Open http://localhost:8000 — the page should render with diagrams, code blocks, and search working. Edit until it looks right.

8. Update the topic overview¶

Open docs/<topic>/index.md and tick off the subtopic in the roadmap so you can see your progress.

9. Commit and push¶

git add .
git commit -m "fastapi: add dependency injection notes"
git push

GitHub Actions rebuilds and publishes the site automatically.

10. Update the home page status¶

In docs/index.md, change the topic's status from 📋 Todo → 🚧 In Progress (or ✅ Done if you've finished the roadmap).

When to ask Claude vs. write yourself¶

Situation	Best move
Brand-new topic, lots of sources	Send Claude the sources, get a structured draft back, then edit.
Already understand it, just need to write it down	Write yourself — faster, and the act of writing cements memory.
Wrote a draft, want a sanity check	Ask Claude to review for accuracy, missing pitfalls, or weak diagrams.
Need a diagram you can't visualize	Describe it in words to Claude, get a Mermaid block back.

Rules of thumb¶

⚠️ Don't paraphrase the docs. If a note just restates the official docs in different words, it adds no value. Add what you found confusing, the diagram you drew to make sense of it, and the pitfall you hit.

⚠️ Always include a diagram. Even a simple flowchart. Future-you's brain pattern-matches on diagrams faster than prose.

⚠️ Always run the code. Snippets you didn't actually execute are snippets that contain a bug.

⚠️ One topic per session. Don't half-write five topics. Finish one, push it, then start the next.

Troubleshooting¶

mkdocs serve fails with a plugin error You're probably missing a dependency. Run pip install -r requirements.txt again.

Mermaid diagram shows as raw text Check the fence syntax — three backticks, then mermaid, lowercase, no extra spaces.

Page doesn't appear in the sidebar You forgot step 5 — add it to nav: in mkdocs.yml.

GitHub Pages shows 404 after push First-time only: go to repo Settings → Pages → Source → "GitHub Actions". Re-run the workflow.

Build passes locally but fails in CI The CI uses mkdocs build --strict which fails on any warning (broken links, missing nav entries). Fix the warning locally first.