Migrate documentation to Astro Starlight#1686
Draft
GreenFlux wants to merge 7 commits into
Draft
Conversation
Replaces the VuePress 1.x docs site with Astro 6 + Starlight 0.38. The previous `docs/.vuepress/` configuration stays in place for now since it's no longer wired into the build pipeline -- a separate cleanup will remove it. Migration highlights: - `docs/astro.config.mjs` configures Starlight with the Rapide theme, Expressive Code (line numbers + collapsible sections), a sitemap, and `starlight-page-actions` (Copy Markdown + Open in ChatGPT / Claude buttons on every page). - Guide pages, the homepage, and the 404 move from the legacy `docs/guide/*.md` + `docs/index.md` tree into `src/content/docs/` and are tracked in git. They were run through the VuePress preprocessor once at migration time, so they now contain Starlight-native asides (`:::tip[Title]`), HTML `<details>` accordions, fully resolved `@[code]` includes, and rewritten links with the `/docs` base prefix. - The TypeDoc-generated API reference is the only path that still passes through `scripts/generate-content.mjs` -- it normalizes TypeDoc's link forms and badge tokens. - The Netlify `_redirects` file (legacy `.html` URLs → clean URLs) is also generated by `generate-content.mjs`, now derived from the tracked content under `src/content/docs/guide/`. - Custom Starlight component overrides for `Head`, `Header`, `Footer`, and `ThemeSelect` reproduce the Handsontable docs look-and-feel (two-row header, sun/moon theme toggle, spreadsheet-style footer). - Root build orchestration (`docs:build` script chain, Netlify build command, GitHub Actions `build-docs.yml`) updated to invoke the Astro build via `npm ci && npm run build` inside `docs/`. Legacy `docs/guide/`, `docs/index.md`, and `docs/api-ref-readme.md` are deleted -- their content lives under `src/content/docs/` now.
Introduces four governance files under `docs/` so contributors -- and AI coding agents -- have a clear, self-contained reference for how to work on the docs site: - `docs/CLAUDE.md`: authoring standards. Diátaxis page-type taxonomy with folder-to-type mapping, voice and style rules with a banned-word list, four page-structure templates (tutorial / how-to / reference / explanation), example-data domain conventions, code-example rules (language tags, `licenseKey: 'gpl-v3'`, builder methods), the frontmatter schema with permanent 8-char IDs and the `| HyperFormula` metaTitle suffix, link conventions, the Excel / Google Sheets trademark notice text, the sidebar registration step, the Starlight-native asides / live-runner HTML pattern, and a PR checklist. - `docs/AGENTS.md`: symlink to `CLAUDE.md` so both naming conventions resolve to the same file. - `docs/README-EDITING.md`: practical reference -- frontmatter long-form, Starlight aside examples, the live-runner HTML pattern with file layout, line highlighting in code blocks, and sidebar registration. - `docs/README-DEPLOYMENT.md`: deployment reference -- Netlify build command, the `docs:build` pipeline (`bundle-all` → `typedoc:build-api` → `npm ci && npm run build`), GitHub Actions CI verification, and the auto-generated `_redirects` map.
The `starlight-page-actions` plugin defaults to rendering its action row directly under the page heading. Match the Handsontable docs UI by moving the actions (Copy Markdown, Open in ChatGPT, Open in Claude) into the right-hand sidebar, below the "On this page" table of contents. Adds two Starlight component overrides: - `PageTitle.astro`: renders only the default page title and drops the plugin's button row. The plugin's override is suppressed because user- configured overrides win over plugin-supplied ones in Starlight. - `PageSidebar.astro`: renders the default TOC, then appends a flat action list styled to match the right-sidebar typography. The Copy Markdown handler reuses the plugin's `.md` companion routes and shows a transient checkmark on success.
✅ Deploy Preview for hyperformula-dev-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
CI flagged two issues on PR #1686: - The `build-docs` GitHub Actions job and the Netlify deploy preview both failed because Astro 6 requires Node >=22.12.0, but every Node pin in the docs setup specified 20. Bump `.nvmrc`, the docs `engines.node` constraint, the `build-docs.yml` job matrix, the Netlify `NODE_VERSION`, and the "Node 20" mentions in the README / CLAUDE.md / README-DEPLOYMENT to 22 (22.12 for the engines pin). - CodeQL flagged `cleanTitleText()` in `vuepress-preprocessor.mjs` for incomplete multi-character sanitization (`js/incomplete-multi-character-sanitization`). A single pass of `/<[^>]+>/g` could leave a `<script>` substring behind for inputs like `<sc<script>ript>`. Iterate the strip to a fixed point so nested tags collapse fully. The downstream consumer (Starlight rendering a YAML `title:`) already escapes HTML, so this is defence-in-depth, but the warning is correct in principle.
Performance comparison of head (720ff8a) vs base (c7cfc9d) |
The Netlify deploy preview for #1686 kept failing with "Node.js v18.20.8 is not supported by Astro" even after setting NODE_VERSION = "22" in netlify.toml's [build.environment]. The deploy log showed Netlify resolving Node from the root .nvmrc ("v18") rather than honoring the netlify.toml env var. Bump .nvmrc to 22 so both sources agree. The HyperFormula library is already exercised on Node 20/22/24 by .github/workflows/build.yml, so bumping the local-dev default to 22 is consistent with what CI already tests.
Astro builds the site with `base: '/docs'`, so generated HTML references `/docs/_astro/*`, `/docs/guide/*`, etc. In production the canonical URL `hyperformula.handsontable.com/docs/` is served by a reverse proxy that strips the `/docs` prefix before forwarding to the Netlify project, so the prefix in the HTML resolves to the right files. Netlify deploy previews (and the netlify.app subdomain in general) don't sit behind that proxy, so `/docs/`-prefixed paths 404 — only the home page rendered, and even then without styles or images because every `/docs/_astro/*` URL came back as a 404. Add a wildcard rewrite to netlify.toml so the preview mimics the production proxy: any `/docs/<path>` request is served from `<path>` in the publish directory. The Astro-generated `_redirects` file is processed first (so the legacy `.html` → clean URL redirects still match), then this catch-all rewrites everything else.
The version pill in the docs header rendered as "v0.0.0" on the Netlify deploy preview even though the same code returned the correct "3.3.0" locally. The cause was the brittle `../../..` arithmetic used to find the library root: in some build environments (apparently Astro's build container on Netlify), `import.meta.url` resolves through a location that's one directory deeper than expected, so three parent hops landed inside `docs/` instead of at the repo root. That made the fallback read `docs/package.json` (version `0.0.0`) instead of the library's `package.json`. Replace the path arithmetic with an upward walk that stops at the first `package.json` whose `name` is `hyperformula`. This is robust to any build-cache layout. While here, also fall back gracefully when the UMD bundle exists but is missing individual fields.
Contributor
Author
|
@sequba @sl01k , this is still a draft, but it's getting close. Here's the latest DP if you want to have a look: |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1686 +/- ##
========================================
Coverage 97.16% 97.16%
========================================
Files 176 176
Lines 15322 15322
Branches 3356 3356
========================================
Hits 14887 14887
Misses 427 427
Partials 8 8 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Status
Draft. Asking for an early structural look — happy to split this into separate PRs if reviewers prefer:
src/content/docs/)CLAUDE.md,README-EDITING.md,README-DEPLOYMENT.md)starlight-page-actionsfeature + the right-sidebar UI placementCurrently three logical commits, easiest to review per-commit:
e227a2479— Migrate documentation from VuePress to Astro Starlightec5c7d126— Add documentation authoring standards and editing/deployment guides510fb6d5a— Move page action buttons into the right sidebarSummary
Replaces the VuePress 1.x docs site with Astro 6 + Starlight 0.38. The previous
docs/.vuepress/configuration stays in place for now since it's no longer wired into the build pipeline — a separate cleanup will remove it.Site structure
docs/src/content/docs/and are tracked in git (no longer regenerated on every build).docs/src/content/docs/api/is the only path still processed byscripts/generate-content.mjs(it normalizes TypeDoc output)._redirectsmap preserves the legacy/docs/guide/<slug>.html→ clean URLs and is auto-generated.Custom Starlight component overrides
Head(Inter font, example-runner client script),Header(two-row HT-style nav with logo + version pill, search, GitHub stars, primary nav, support dropdown),Footer(link grid + social row),ThemeSelect(sun/moon toggle),PageTitle+PageSidebar(moves the Copy Markdown / Open in ChatGPT / Open in Claude buttons into the right sidebar under "On this page", matching the HT docs layout).Plugins
starlight-theme-rapide(typography + chrome) andstarlight-page-actions(page-action buttons + auto-generated.mdcompanions next to each.html).Authoring governance
docs/CLAUDE.md(symlinked fromdocs/AGENTS.md) — Diátaxis-based authoring rules, frontmatter schema with permanent 8-char IDs, code-example conventions (licenseKey: 'gpl-v3', builder methods), Excel/Google Sheets trademark callouts, and a PR checklist.docs/README-EDITING.md— practical reference for Starlight-native asides, the live-runner HTML pattern, and sidebar registration.docs/README-DEPLOYMENT.md— Netlify build chain,docs:buildpipeline, GitHub Actions CI verification.Build wiring
netlify.tomlrunsnpm run docs:buildfrom the repo root and publishesdocs/dist..github/workflows/build-docs.ymlruns the same command on PRs and pushes tomaster,develop,release/**.docs:buildscript chains:bundle-all→typedoc:build-api→cd docs && npm ci && npm run build.Test plan
::: exampleblock (e.g./docs/guide/basic-usage), and an API ref page (e.g./docs/api/classes/hyperformula).mdcompanion, Open in ChatGPT / Open in Claude prefill a prompt.htmlURL redirects in_redirectsresolve (e.g./docs/guide/basic-usage.html→/docs/guide/basic-usage)npm run docs:buildfrom the repo root completes without errorsKnown follow-ups (not in this PR)
docs/.vuepress/directoryCLAUDE.md§9