Why I started the Encyclopedia project with a file format and a validation spec instead of content: a typed frontmatter schema, ids that encode their own rules, prerequisites as a graph that must stay acyclic, and an honest look at what mass AI-assisted generation does and doesn't give you.
It is easy to produce a lot of text. It is hard to produce a lot of text that stays consistent. When I started a CS knowledge base, I wrote the structure down before writing any content, on the theory that a bad format costs more the more content you pour into it. This post describes that format and what I'd check next.
Every piece of knowledge is one markdown file with frontmatter:
| Field | Purpose |
|---|---|
id | Globally unique, lowercase-word-word-number (e.g. acid-001) |
kind | One of subject, unit, topic, subtopic, concept, lesson |
parent_id | The node one level up |
difficulty | beginner / intermediate / advanced |
tags | At least one |
prerequisites, related_to | Optional lists of other ids |
The body is a fixed ten-section skeleton: overview, explanation, real example, key takeaway, related concepts, quiz, interview questions, code example, references. A fixed skeleton sounds rigid, but it means a reader always knows where to look, and a validator can check structure mechanically.
Folders mirror the hierarchy for human browsing, but the truth is parent_id. That makes moving a file harmless to the graph and lets a concept be re-parented by editing one field. It also means a validator has a precise job: check that every parent_id resolves to a real node.
The spec lists the checks a validator must enforce. They fall into three groups:
Per-file (local): frontmatter present with required fields; id format; allowed difficulty and kind values; at least one tag; all ten sections present and in order; at least two quiz questions; at least two interview questions with expected answers.
Cross-file (referential): ids unique across the corpus; every prerequisite and related_to resolves; parent_id resolves; in-body links like [text](some-id-001) point to real nodes.
Graph-level: no circular prerequisites. If A requires B and B requires A, a learning path can't be computed. Detecting that is a standard cycle check (depth-first search with a visiting set, or Kahn's algorithm) and it is the one rule that can't be checked by looking at a file in isolation.
Because the rules are written as a spec, the validator's expected output is also specified: per-file failures with the rule broken and how to fix it, and a summary report.
The validator doesn't exist. That's the honest status, and it matters because of the next section.
The corpus is produced with AI assistance, through scripts that emit node files. The format makes that safer, not correct:
data/ folder for exactly that.My plan is to finish the validator first, then take one subject through review end to end — checking facts, running the code examples, trimming repetition — before generating anything more. A small reviewed corpus is more useful than a large unreviewed one.
parent_id, prerequisites), not in the folder tree.A Database-Free Content App — Parsing Markdown at Build Time in Next.js (and Doing Attribution Properly)
How the Roadmaps app turns about 94 folders of markdown into a typed, searchable site without a database: a small parser with regexes for resource lines, memoised file-system reads, title-casing rules, and the licensing hygiene of building on someone else's open-source content.
Trusting AI Drafts Less — Validation Flags, Versioned Sections and Human-in-the-Loop Edits
How Beacon keeps a generated document reviewable: rule-based gap detection, an LLM check for requirement-versus-decision contradictions, append-only section versions with human-edit locking, and natural-language edit requests that go through the same ledger.
Building PSM — An Offline Music Player That Lives Entirely in the Browser
Notes from building PSM, an installable iPhone music PWA with no backend: why the library lives in IndexedDB, how the app is split into a thin data layer, one audio element and a store, and what a same-day v1 looked like commit by commit.