2026-04-18-frontmatter-track-indexes-design

Frontmatter-Driven Track Indexes

Date: 2026-04-18 Status: Approved Branch: notebooks-microstructure (will be a separate branch)

Problem

Three hardcoded reading orders must be kept in sync manually:

• study-guide.md — Track A (18 steps, cross-directory) + Track B (4 steps)
• market-microstructure/_index.md — 7 articles
• defi-markets/_index.md — 6 articles

Adding or reordering a note requires editing up to three files. The study guide duplicates metadata (time estimates, focus points) that could live in the notes themselves. There is no way to export a track as a single document for tools like NotebookLM.

Design

1. Frontmatter schema (two new fields)

Every finance note that belongs to a learning track adds:

tracks:
  - id: main
    step: 9
  - id: defi
    step: 2
notebook: "code/defi-constant-product-amm/notebook"

tracks — list of {id, step} pairs. Optional. Notes without tracks (e.g., aig-and-the-cds-crisis.md) omit the field entirely.

notebook — optional wikilink target for the companion notebook.

Track IDs

Track ID	Current source	Notes
main	study-guide.md Track A, steps 1-18	Cross-directory main path
microstructure	study-guide.md Track B, B1-B4	Academic deep dive
defi	defi-markets/_index.md, 2.1-2.6	Per-directory DeFi sequence

The mev and derivatives sub-sequences are part of main (they have step numbers within it), not separate tracks.

Full frontmatter example

---
title: "2.2 -- Constant-Product AMM"
date: 2026-03-20
tags: [defi, amm, uniswap, math]
draft: false
tracks:
  - id: main
    step: 9
  - id: defi
    step: 2
notebook: "code/defi-constant-product-amm/notebook"
source_conversations:
  - id: "ae02a575-..."
    note: "Crypto pump business models"
---

2. Generation script

docs/scripts/generate-track-pdf.py — a Python script with uv inline metadata (dependencies: pyyaml, pathlib).

uv run docs/scripts/generate-track-pdf.py --track main -o finance-main.md
uv run docs/scripts/generate-track-pdf.py --track main -o finance-main.pdf

Logic:

1. Walk 2 - Areas/Finance/**/*.md
2. Parse YAML frontmatter from each file
3. Filter: keep notes where any tracks[].id == <track>
4. Sort by the matching tracks[].step
5. Output format based on extension:
   • .md — concatenate with --- separators and a generated TOC
   • .pdf — concatenate to temp .md, pipe through pandoc

The .md output is the primary target (NotebookLM accepts markdown). PDF is a convenience for other tools.

3. Dataview queries (replace hardcoded indexes)

The _index.md files can optionally use Dataview TABLE queries instead of handwritten tables:

TABLE title AS "Article", notebook AS "Notebook"
FROM "2 - Areas/Finance"
WHERE contains(tracks.id, "defi")
SORT tracks.step ASC

This is optional — the _index files can stay handwritten if Dataview isn’t installed. The script is the authoritative generator.

4. Study guide

study-guide.md keeps its rich content (focus points, readiness checks, tips). The frontmatter tracks field is the source of truth for ordering. The study guide references notes by wikilink and the order comes from the step values. If notes are reordered, only frontmatter changes — the study guide prose stays stable because it references notes by name, not by position.

Migration plan

1. Add tracks and notebook fields to all ~30 finance notes that belong to a track (12 remaining notes have no track).
2. Remove ordering numbers from titles (e.g., “2.2 — ” prefix in constant-product-amm) — the step lives in frontmatter now.
3. Write generate-track-pdf.py.
4. Verify: uv run generate-track-pdf.py --track main produces the correct 18-note sequence.
5. Clean up duplicate trading-venues.md (exists in both Finance/ root and market-microstructure/).

Out of scope

• Replacing study-guide.md with a generated file. The study guide has rich pedagogical content (focus points, readiness checks) that can’t be generated from frontmatter alone.
• Dataview plugin installation or configuration.
• CI/CD integration for PDF generation.