docs: migrate heartKIT to Astro and shared HELIA navigation - #44
Merged
Merged
Conversation
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
HANDOFF.md still presents completed reviews and dependency validation as pending.
Review effort: Balanced
Findings: 1
Open (1)
What changed in this PR
Migrates heartKIT documentation from MkDocs to Astro/Starlight with shared HELIA navigation, generated API references, preserved notebooks, and independent Pages deployment.
Changes:
- Adds the Astro/Starlight documentation site and responsive HELIA interface.
- Converts authored content, notebooks, API references, and legacy routes.
- Adds comprehensive build, output, browser, and deployment validation.
| File | Description |
|---|---|
.github/workflows/docs.yaml |
Builds, verifies, and deploys documentation. |
.gitignore |
Excludes generated Astro artifacts. |
AGENTS.md |
Documents the new maintenance workflow. |
HANDOFF.md |
Records migration status and validation. |
astro-site/.nvmrc |
Selects Node 24. |
astro-site/MIGRATION.md |
Documents migration coverage and limitations. |
astro-site/README.md |
Provides site development instructions. |
astro-site/astro.config.mjs |
Configures Astro, Starlight, HELIA, and redirects. |
astro-site/package-lock.json |
Locks site dependencies. |
astro-site/package.json |
Defines dependencies and build scripts. |
astro-site/playwright.config.ts |
Configures browser tests. |
astro-site/scripts/build-content.mjs |
Converts MkDocs Markdown into Astro content. |
astro-site/scripts/build-notebooks.py |
Renders saved notebook content and outputs. |
astro-site/scripts/build-reference.mjs |
Generates the public Python reference. |
astro-site/scripts/check-output.mjs |
Validates generated routes, links, and assets. |
astro-site/scripts/legacy-routes.json |
Records historical published routes. |
astro-site/scripts/normalize-markdown.mjs |
Normalizes Material-specific Markdown. |
astro-site/scripts/normalize-markdown.test.mjs |
Tests Markdown conversion behavior. |
astro-site/scripts/public-docs.mjs |
Defines public API filtering. |
astro-site/scripts/publish-reference.mjs |
Publishes API Markdown and enhanced redirects. |
astro-site/scripts/test-build-notebooks.py |
Tests notebook prose preservation. |
astro-site/src/components/ConfigExample.astro |
Adds collapsible downloadable configurations. |
astro-site/src/components/HomeHero.astro |
Adds the branded heartKIT hero. |
astro-site/src/content.config.ts |
Defines the Starlight content collection. |
astro-site/src/navigation.mjs |
Defines section-scoped navigation. |
astro-site/src/section-matcher.ts |
Matches routes to navigation sections. |
astro-site/src/styles/site.css |
Styles documentation content and components. |
astro-site/tests/site.spec.ts |
Tests navigation, notebooks, redirects, and examples. |
astro-site/tsconfig.json |
Enables strict Astro TypeScript settings. |
docs/assets/usage/json-configuration.md |
Corrects configuration syntax highlighting. |
docs/assets/zoo/beat/beat-model-zoo-table.md |
Restores beat model results. |
docs/assets/zoo/denoise/denoise-model-zoo-table.md |
Restores denoising model results. |
docs/assets/zoo/rhythm/rhythm-model-zoo-table.md |
Restores rhythm model results. |
docs/assets/zoo/segmentation/segmentation-model-zoo-table.md |
Restores segmentation model results. |
docs/index.md |
Reworks landing and installation content. |
docs/models/index.md |
Repairs the architecture example. |
docs/modes/configuration.md |
Corrects table formatting. |
docs/modes/evaluate.md |
Simplifies examples and workflow diagram. |
docs/modes/export.md |
Simplifies examples and workflow diagram. |
docs/modes/index.md |
Reworks the workflow overview. |
docs/modes/train.md |
Simplifies examples and workflow diagram. |
docs/quickstart.md |
Updates requirements and configuration examples. |
docs/tasks/beat.md |
Repairs model-zoo linking and JSONC labeling. |
docs/tasks/diagnostic.md |
Adds introductory context. |
docs/tasks/index.md |
Replaces task tabs with a comparison table. |
docs/tasks/rhythm.md |
Converts rhythm tabs into headings. |
docs/tasks/segmentation.md |
Corrects JSONC labeling. |
docs/usage/python.md |
Removes obsolete annotations. |
heartkit/assets/__init__.py |
Documents bundled asset resources. |
heartkit/assets/data/__init__.py |
Documents packaged noise recordings. |
heartkit/datasets/augmentation.py |
Repairs a docstring code fence. |
heartkit/models/__init__.py |
Converts the model example wrapper. |
heartkit/utils/plotting.py |
Repairs the plotting example. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| Content review identified two migration regressions: removing a Colab toolbar discarded BYOT prose in the same cell, and static redirects discarded API symbol fragments. The renderer now removes only toolbar markup; redirects preserve query strings and fragments with a meta-refresh fallback when JavaScript is disabled. Both changes have regression coverage. Delivery review checked Pages permissions and triggers, shared section matching, notebook assets, public API coverage and Python AST parity. No additional blocking findings remained after fix review. | ||
|
|
||
| Dependency qualification: shared UI alpha.21 is pinned by immutable commit `6cdbea0c594c955e6aeef232af1fbb15e395ab2d` (AmbiqAI/helia-ui#183 and #184). Clean installation, type checks, build, output checks and all eight browser tests pass with this dependency. |
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
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.
heartKIT documentation still uses MkDocs and its navigation, code examples and notebook rendering do not match the migrated HELIA sites. Migrate to Astro/Starlight with the shared HELIA UI, a red heartKIT hero, section-scoped navigation and a mobile section dropdown.
Preserves 44 authored pages, five saved notebooks with downloadable sources and 18 figures, and all 190 original published URLs. Generates the public Python API without importing training dependencies. Configuration examples have collapsed previews and downloads; tables, task summaries and workflow diagrams are repaired. Python changes are docstrings only.
The Pages workflow builds and verifies pull requests and deploys only main. Package release workflows are unchanged. Runtime updates, model refreshes and Hugging Face publishing remain separate work.
Review and validation
Two independent content and delivery reviews identified lost BYOT introductory prose and legacy API redirects losing symbol fragments. Both are fixed with regression coverage and re-reviewed.
Dependency and approval
Shared UI alpha.22 is released. The immutable dependency commit
a62e8d45505dd3bbcdf1c4a03dfd1ec863322ecfmatches tagv0.1.0-alpha.22(AmbiqAI/helia-ui#185 and #186). This includes mobile section navigation and compact terminal frames inside tabs. Clean installation, type checking, build, output validation and all eight browser tests pass with this release. heartKIT merge and deployment require owner approval; other product documentation updates follow heartKIT.Historical model metrics, training examples, external links and dataset availability were not requalified. See astro-site/MIGRATION.md for coverage.
Closes #43.