Design: move sidebar ordering out of the toolbox READMEs and off absolute sort numbers

[philipcardiff]

Ordering metadata for the website sidebar currently lives as sort: front
matter inside the READMEs in solids4foam/solids4foam. Only the website
consumes it, so a toolbox contributor adding a README has to know about, and
pick a number in, a sequence that is defined entirely by another repository.
#86 is one symptom of this; the underlying design is worth revisiting on its
own.

Filing for discussion — no change proposed yet.

Current state

Measured against the submodule pointer on master (2b36cba5):

• 116 README.md files in the toolbox; 111 carry front matter
• sort: is the only front-matter key in any of them — not even title:
  (titles come from the H1)
• every published Documentation and Tutorials page is a symlink into
  imported/solids4foam, generated by bin/sync-docs.sh from
  bin/docs-manifest.txt
• the sidebar reads sort in _includes/common/rest/site_pages.liquid
  (ordering) and _includes/templates/_toctree.liquid (display)

So the coupling between the two repositories is exactly one field. If it moved,
the toolbox READMEs would be plain markdown with no front matter at all.

Two problems, not one

1. The numbers are absolute positions in a global sequence. This is what
causes gaps (#86), renumbering churn when a page is inserted, and the "what
number do I pick?" question. It would still be a problem even if the numbers
lived in this repository.

2. They live in the toolbox. This is the cross-repository coupling: a
toolbox contributor must think about the website's sidebar, and a change to
ordering has to travel through a submodule bump to take effect.

(1) is the higher-value fix and is independent of (2). If ordering is expressed
as position in a list rather than a number written into a file, the
generator can emit 1, 2, 3, … contiguously every time and gaps become
impossible by construction.

bin/docs-manifest.txt is already a complete website-side registry of every
published page — it simply carries no ordering today (it is sorted
case-insensitively by site path). Giving it an explicit order column, or making
it section-grouped with line order significant, turns a file we already
maintain into the single source of ordering truth.

Constraint that shapes the options

Jekyll only renders files that have front matter. A README with no front
matter becomes a static file rather than a page. So "delete sort: and add
nothing" does not work on its own — the front matter has to come from
somewhere.

Options

A. Wrapper pages

Stop symlinking the README as the published page. The published page becomes a
real file in this repository:

---
sort: 4
---

{% include_relative _source.md %}

with _source.md the symlink into the submodule. sync-docs.sh generates the
wrappers from the manifest exactly as it generates symlinks today.

• Toolbox READMEs need no front matter at all — fully achieves the goal
• Ordering is legible at the page it applies to, no large generated config block
• READMEs render cleanly on github.com without a stray YAML block
• No plugin needed; works on stock GitHub Pages
• Unverified: whether include_relative resolves a symlink into
  imported/ under --safe, which is how GitHub Pages builds. It should —
  imported/ is inside the site source, and the exclude: entry does not
  affect includes — but this is the assumption the option rests on and needs a
  short spike before committing
• Also needs checking: how readme_index behaves when the section index is a
  wrapper rather than the symlinked README, and that relative image links still
  resolve against the existing images/ symlink machinery

B. _config.yml defaults

Jekyll's defaults: can set sort per path; generate that block from the
manifest.

• Mechanically simpler than A, no change to how pages are produced
• Front matter in a file overrides defaults, so the upstream sort: lines
  must genuinely be deleted first — this is a prerequisite, not optional
• Each README still needs an empty ---\n--- to remain a page, so we do not
  fully reach "contributors never think about front matter"
• Produces a ~130-entry generated block in _config.yml; machine-managed and
  coverable by sync-docs.sh --check, but noisy

C. Own the build, use a plugin

Replace the stock pages-build-deployment with an Actions workflow running
jekyll build + actions/deploy-pages. That unlocks _plugins/, so a small
Generator could read _data/docs-order.yml and set page.sort directly — no
wrappers, no config bloat.

• Cleanest end state
• Independent benefit: the stock Pages build pins us to Jekyll 3.9 / Liquid
  4.0.3, which breaks on Ruby ≥ 3.2. Local builds currently need a Ruby 3.1
  container. Owning the build lets us pin a modern toolchain
• Largest commitment: we become responsible for the deploy path

Trade-off worth naming

Ordering is arguably editorial content — the person writing neoHookeanElastic
is best placed to say it belongs after StVenantKirchhoffElastic. Moving order
into this repository means that judgement gets expressed in a website PR rather
than alongside the prose. That still seems right, since the global sequence
is a website concern, but the manifest should be grouped and commented by
section so the intent stays readable rather than becoming an opaque list of
paths.

Suggested direction

A for the ordering mechanism, with the manifest as the source of truth and
generated contiguous numbers; C separately, on its own merits, whenever there
is appetite. B is the fallback if the include_relative spike fails.

Related: #86 (the gap at sort: 4), #84 (made the numbering visible), #83.