Roadmap

NOTE

This is a high-level direction document, not a spec. It maps the gap between what exists today and a full docs platform (Docusaurus / Mintlify style), split into an old way (classic docs features) and a new way (an AI assistant over the content). Each item here is still a headline — the individual topics need their own deeper write-up before they're built.

Where we are

This isn't a blank slate. Today the site already ships much of what a docs platform is made of:

  • Three-column shell — resizable, with a mobile drawer.
  • Markdown with GFM, callouts, syntax highlighting, anchors, and [[wiki-links]] for cross-linking (something Docusaurus lacks out of the box).
  • Tags plus a tag index and per-tag pages.
  • Search (⌘K, backed by a build-time index).
  • "On this page" outline with scroll-spy.
  • Prev / next pager between projects.
  • Reading-size toggle and reader mode.
  • Automatic dark mode.
  • Changelog page.
  • "View as Markdown" + copy page (on docs / project pages).
  • Edit on GitHub + Last updated on projects and the top-level pages.
  • Content-type-aware page controls (docs vs. article vs. standalone page).

Realistically that's ~70% of a full docs platform. The work ahead is the last 30%, not a rebuild.

Old way — toward full docs

Ordered by value-to-effort for this use case (a personal docs / thought sorter).

Reading experience — sidenotes & full-bleed figures

Inspired by research blogs like Thinking Machines' Connectionism (Hugo). Markdown-native — no MDX, no per-page hand-coding.

  • Figures that break the measure — done. Body text keeps its reading width, but a photograph can run wider. Standalone images render as captioned figures; ![Caption](/img.jpg "wide") breaks past the measure; several images in a paragraph become a gallery; and every figure image is zoomable — click for a fullscreen lightbox. (A wide Mermaid diagram is the same fig-wide opt-out, not yet wired.)
  • Sidenotes / margin notes — next. Footnotes and asides float in the margin next to the text they annotate, instead of stacking at the foot. GFM footnotes ([^1]) already parse for free, so this is mostly rendering them into the margin (with an inline / foot fallback on mobile) — no new syntax.

Sidenotes lean on the grid: project pages already run four columns (nav · index · content · "on this page"), and a margin note wants the same right margin as the outline. The likely unlock is moving the main nav to a top bar (freeing the left side) so the outline and sidenotes stop competing — a layout refactor to settle first, and the gate on the sidenotes. A "cite this page" block generated from frontmatter is an optional academic finish. Out of scope: inline interactive / animated figures — they'd break the "content is just .md" rule.

Related topics / "Next steps" cards

Three footer cards (icon + title + summary), Mintlify-style — but data-driven, not hand-maintained. Drive them from frontmatter (related: [[reading]]), reusing the existing getLinkTargets() wiki resolver, and optionally auto-suggest pages that share tags so they never go stale.

Edit this page + Last updated — done

An "Edit on GitHub" link and a git-derived "Last updated" date, now on projects and the top-level pages (information, contact, roadmap, changelog). The page chrome is content-type aware: docs (projects) keep the source tools (Copy page / View as Markdown), articles (news) drop them in favour of plain reading, and standalone pages get just the reading-size control plus this footer.

Feedback — "Was this page helpful?"

Honestly low priority while this is single-reader; it's a signal from readers. When it lands: thumbs up/down (not stars or smileys — that's the docs standard), with an optional "what was missing" on a down-vote. Needs a sink (this site has no DB): Vercel KV / a Marketplace store, or a serverless route that opens a GitHub issue.

Nested / collapsible sidebar

The project list is currently flat. Full docs group pages into collapsible sections. Introduce a group frontmatter key when the content outgrows a flat list — not before.

SEO + Open Graph + sitemap / RSS

Per-page title/description from frontmatter, generated OG images (next/og), sitemap.xml, robots.txt, and an RSS feed for the changelog. Cheap with Next.js natives; matters once the site is public.

Richer content components

Tabs, Steps, Accordion, Card grids, Mermaid diagrams, KaTeX math (image zoom is already done — see Reading experience). Add reactively, driven by what the content actually needs — not up front.

New way — AI assistant

The plan is to reuse the "Kluky" architecture already built in the nplusbike project (AI SDK v6, a model-agnostic provider factory, streamdown streaming, a ⌘K sidebar, per-request token / latency / cost logging). The only real change is the knowledge base: there it's a live database; here it's the static .md content.

  • Approach: tool-calling over lib/content.ts rather than a vector store — the corpus is small. Give the model thin tools (searchDocs, readPage, listPages) so it finds and reads the right pages, then answers with citations (which page the answer came from). Embeddings only become worth it if the corpus grows large.
  • llms.txt / llms-full.txt: generate both at build time from the same content pipeline. This is the bridge between the two ways — it lets external AI (Claude, ChatGPT) read the docs, and feeds our own assistant cheaply.

Reuse — make it a template

A parallel track: stabilise the engine so a fresh site can be spun up with one command. The engine (app/, components/, lib/, styling) is stable; only the content (content/*.md) changes per site, so "templatizing" means shipping clean placeholder content plus an easy way to instantiate. Lightest to heaviest:

  • GitHub template repo — flip the "Template repository" switch; new sites start from gh repo create <name> --template <repo> (or the "Use this template" button), each with its own git history. Lowest effort, recommended first step.
  • degit — npx degit <user>/<repo> my-site clones without git history for a quick local copy. No publishing; pin a known-good version with #v0.4.0.
  • create-… npm package — publish a small scaffolder so npm create boilerplateau@latest my-site works like npm create vite. Worth it only for public distribution or an interactive setup (prompt for title / author).

Note: npm i -g <pkg> is a global CLI install — a different category. This is project scaffolding (create-* / degit / template repos). Groundwork: tag releases (git tag v0.4.0, none exist yet) and keep a clean placeholder content/ set so personal notes don't ship with the template.

Priority order

A rough sequence, not a commitment:

  1. llms.txt + AI assistant — the natural first move and the bridge between the old and new ways. (Next to be deepened into a real plan.)
  2. Related cards (frontmatter + auto-from-tags).
  3. SEO / OG / sitemap — when the site goes public.
  4. Feedback widget — only once others read it.
  5. Sidenotes / margin notes — the remaining half of Reading experience (wide figures + lightbox already shipped); gated on the grid / top-bar refactor.
  6. Nested sidebar and richer components — reactively, as the content asks for them.
  7. Template / distribution — when the engine is worth reusing for another site (GitHub template + degit first; an npm create package only if it goes public).