Skip to content

Conventions & Page Architecture

Reference for creating and editing pages. Read when writing new content or running builds.

Page Roles (avoid repetition)

Each page has a single clear purpose. Do not duplicate data across pages:

Page Role Contains Does NOT contain
current-plan.md Single source of truth for strategy Targets, policies, allocation, FIRE status, drawdown timeline, decision history Raw numbers, fund balances, analysis
action-items.md Task tracker Open/completed tasks with owners Strategy, numbers
wife-summary.md Julia's overview (for reading) Warm summary, milestone projections, ages Technical analysis, fund codes
assessment.md Analysis & reasoning (for reading) Findings, recommendations, rationale, risk scenarios, projections Raw balances, fund-level data (reference snapshot instead)
snapshot.md Data dump (for record-keeping) Balances, charts, cash flow, FX, vesting schedule, history Strategy, targets, opinions, recommendations, analysis
*-proposal.md Specific proposals (session) Detailed proposal for one change (e.g. rebalance) Final decisions (those go in current-plan)
index.md Session overview What was covered, key decisions list, pending actions Data, analysis

Rule: If you find yourself writing the same table or number in two pages, ask: "Which page owns this?" Put it there, link from the other. Assessment references snapshot data — it does not repeat it.

Wife Summary Requirements

Every session must produce a wife-summary.md in the current month's folder — a warm, high-level overview for Julia covering: where we stand financially, the outlook, any exciting milestones or changes, and what actions were taken or planned. Keep it positive, jargon-free, and reassuring. Update (not replace) if multiple sessions occur in the same month.

Must include:

  • Ages of family members at key milestone dates (e.g., "Henry will be 18", "Jonathan will be 47")
  • A clear "what if we stop working today" section showing the family can hit targets purely from investment growth
  • Specific dollar projections at key life events

Markdown Formatting Rules (critical for MkDocs rendering)

MkDocs requires blank lines to separate block-level elements. Without them, content renders inline or breaks entirely.

  • Always leave a blank line after a heading before any content
  • Always leave a blank line before a table — otherwise it won't parse as a table
  • Always leave a blank line before a bullet/numbered list — otherwise it renders inline with the preceding paragraph
  • Always leave a blank line before and after code blocks
  • Always use relative links — never absolute (/page.md). From root files use monte-carlo.md; from session files use ../../monte-carlo.md. The build warns on absolute links.
  • Anchors from headings: MkDocs strips special chars (em-dashes, dots, colons) and collapses hyphens. E.g. ### 3. Tax Structure — PIE → #3-tax-structure-pie
  • Cross-link mentions of other pages (e.g., Monte Carlo, Current Plan) to their actual pages

Site & Build Conventions

  • build.sh generates everything — never manually edit docs/ or mkdocs.yml
  • current-plan.md and action-items.md must be updated every session
  • Session nav order is prescribed: Overview → Wife Summary → Assessment → Snapshot → Plans & Proposals → remaining
  • Files with "plan" or "proposal" in the name auto-group under "Plans & Proposals" in nav
  • Sessions are grouped by year in the nav
  • The Monte Carlo page auto-injects the latest portfolio value from the most recent snapshot
  • Use sed ... > tmp && mv tmp file pattern (not sed -i) for portability across macOS and Linux

Content Rules

  • No superseded content — all pages must reflect final, current thinking only. If a decision changes, update the page to show the new decision. Do not mark old content as "superseded" or leave stale data with disclaimers. Git history preserves the record.
  • Snapshots are immutable — once a month closes, never edit that month's snapshot.md. It is a point-in-time record. Corrections go in the next month's snapshot. The same applies to wife-summary.md and index.md for closed months — they are historical documents.
  • No file references in rendered pages — don't write "(from StockExport.xlsx)" etc. in markdown that renders on the site.
  • No inline <style> blocks — all CSS lives in overrides/extra.css. See guidance/design-guidelines.md for components.
  • Always state assumptions clearly
  • Flag when data is stale and request updates