feat(nav): honor frontmatter order and description, add prev/next links

[llbbl]

Summary

• Navigation was purely alphabetical (by title) with no way to control article or folder order, and the real frontmatter description was discarded, so every meta description and og:description was the title repeated. There was also no prev/next navigation within a folder.
• Two nullable columns (sort_order and description) now persist this data in the search table, populated by a post-index pass and read through one explicit-column query, with folder sequence controlled from a single config file.
• Article pages now emit the real description and prev/next links within their folder.

Problem

Four separate gaps: alphabetical article order with no order frontmatter, incidental folder order (whatever order a folder's first article happened to sort into), description discarded by libsql-search so every <meta name="description"> and og:description was the title repeated, and no prev/next links.

Where the data lives

The libsql-search table has no description or order column, so this project persists both. Two nullable columns (sort_order — order is a SQL keyword — and description) are written by a post-index pass that is a sibling of the existing keyword-index rebuild, and read by one query that selects an explicit column list rather than SELECT * so article bodies are not dragged into the build. Nothing reads ./content at render time, which keeps one source of truth and works where content is not colocated with the server.

Upgrade path

CREATE TABLE IF NOT EXISTS will not add a column to an existing table, so ensureNavColumns does a PRAGMA table_info check plus ALTER TABLE ADD COLUMN. Verified against three real pre-existing database states: a populated pre-migration table, an index:local run with no prior db:init, and the repo's own local.db created before this branch. Idempotent, handles a partial earlier migration, and throws rather than silently no-op'ing when the table is absent.

Sort semantics

Within a folder, order ascending, then title, then slug. Slug is UNIQUE so the comparator is a total order and builds are deterministic. An article without order sorts after every article that has one; order: 0 counts as declared, not absent. localeCompare is pinned to 'en' so a build machine's locale cannot change page order. Folders follow src/config/nav.ts; unlisted folders sort after listed ones, alphabetically, and listing every folder is not required.

Fail-loud on a stale database

The new query selects the new columns, so a database that never ran db:init/index now fails at build time rather than serving pages in the wrong order. All three page routes are prerendered and neither API endpoint touches these columns, so there is no runtime path that can 500 — a stale deployment simply cannot be built. The error now names the commands to run instead of only the missing column.

Review findings applied

• gray-matter moved from devDependencies to dependencies — it was imported by a shipped script, and pnpm install --prod leaves it unresolvable at the project root, so pnpm install --prod && pnpm index on a deploy host would crash with ERR_MODULE_NOT_FOUND. Being a transitive dependency of libsql-search makes this worse rather than better under pnpm's strict layout, since it is symlinked only into that package's own tree. The move costs three lockfile lines and no new package.
• The post-index pass now reports rows matched rather than files read, and warns on a shortfall, so a slug divergence can no longer print a confident success line while the sidebar silently falls back to title order.
• The file walk now honors the indexer's own exclude list.
• The file list is sorted so duplicate-slug resolution is deterministic, matching the library.

Test gaps closed

A test that asserted the old files-read count is inverted to assert rows matched. The shipped folder configuration is now pinned — proven load-bearing, emptying src/config/nav.ts fails it, where previously the whole suite passed.

Verification

428 tests pass, lint and tsc --noEmit clean, credential-free build and smoke pass. Built output confirms the sidebar renders Getting Started → Features → Theme where alphabetical would give Features first, and both meta description tags carry the real frontmatter text.

Worth knowing

Prev/next does not appear in the shipped demo because each of the three folders holds a single article. All four boundary cases were verified with temporary fixtures — first has no prev, last has no next, single-article folder emits no nav element, and links never cross a folder boundary — then the fixtures were removed. Shipping a second article in one folder would make the feature visible to anyone evaluating the theme.

Closes #106

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.09%. Comparing base (9cd11b0) to head (5c4852f).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #129      +/-   ##
==========================================
+ Coverage   94.43%   95.09%   +0.65%     
==========================================
  Files          19       22       +3     
  Lines         539      611      +72     
  Branches      144      170      +26     
==========================================
+ Hits          509      581      +72     
  Misses         12       12              
  Partials       18       18              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.