diff --git a/web-astro/.gitignore b/web-astro/.gitignore new file mode 100644 index 00000000..ca9d34d8 --- /dev/null +++ b/web-astro/.gitignore @@ -0,0 +1,32 @@ +node_modules/ +dist/ +.astro/ + +# Generated by tools/convert-book.mjs (RST→MDX whole-book conversion). +# Regenerate with: npm run convert (also runs automatically on predev/prebuild) +/src/content/docs/behavior/ +/src/content/docs/components/ +/src/content/docs/front/ +/src/content/docs/advanced.mdx +/src/content/docs/todo.mdx +/tools/sidebar.gen.json +/src/content/docs/genindex.mdx +/public/figures/ + +# Generated by tools/build-locales.mjs, which applies the tracked gettext +# catalogs in text/locale/ onto the English MDX. Both inputs are in the repo, +# so these are cheap to rebuild: npm run convert +/src/content/docs/ar/ +/src/content/docs/cn/ +/src/content/docs/de/ +/src/content/docs/es/ +/src/content/docs/fr/ +/src/content/docs/it/ +/src/content/docs/kr/ +/src/content/docs/pt_BR/ +/i18n/po/ + +# NOT ignored, deliberately: public/plots/*.svg and src/cases/*.json. +# Both derive from text/results/ (DVC output) and text/plots/ (itself +# gitignored), so neither can be rebuilt from a clean clone without a DVC +# pull and a containerised simulation run. They are committed as artifacts. diff --git a/web-astro/FEATURE-MAP.md b/web-astro/FEATURE-MAP.md new file mode 100644 index 00000000..cf613398 --- /dev/null +++ b/web-astro/FEATURE-MAP.md @@ -0,0 +1,56 @@ +# Sphinx → Astro/Starlight feature parity map + +Every Sphinx feature the book actually uses (counted across `text/source/**/*.rst`) +mapped to its Astro + Starlight equivalent. Status legend: + +- **Native** — built into Astro/Starlight, no extra work. +- **Plugin** — an npm remark/rehype plugin + config (not a fork). +- **Component** — an MDX component we author (like `SimFigure`). +- **Gap** — no drop-in; needs a custom plugin or a product decision. Flagged. + +## Directives + +| Sphinx directive | Uses | Astro/Starlight equivalent | Status | Notes | +|---|---:|---|---|---| +| `code-block` | 293 | Fenced ` ```lang ` via Expressive Code | **Native** | Shipped with Starlight. Modelica has no Shiki grammar → renders as plain text (add a TextMate grammar later; mystmd is no better). | +| `literalinclude` | 285 | `?raw` import + `` | **Native** | Demonstrated in the slice — code stays sourced from the `.mo` files. `:lines:`/`:emphasize-lines:` = a slice/mark helper. | +| `index` | 232 | Pagefind full-text search (built in) | **Gap→decision** | Starlight ships site search, which largely supersedes a hand-maintained index. A literal back-of-book index page would need a small remark plugin. Recommend: drop in favor of search unless a print index is required. | +| `math` (block) / `:math:` (inline) | 106 / 404 | `remark-math` + `rehype-katex` | **Plugin** | Wired in the slice; renders via KaTeX. | +| `plot` + `:class: interactive` | 104 | `` MDX component | **Component** | The bake-off centerpiece — native MDX component, no fork. | +| `figure` | 80 | Markdown image / `
` component | **Native** | Rendering is native; **auto-numbering** ties to the cross-ref gap below. | +| `toctree` | 21 | Starlight `sidebar` (manual or `autogenerate`) | **Native** | Different model — nav is site config, not in-content. | +| `topic` | 18 | `:::note` / `