Repository navigation
Migrate documentation website from Hugo to Astro - #758
Merged
Merged
Conversation
alejandro-ao
marked this pull request as ready for review
October 6, 2026 10:51
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
The 404 page loses noindex metadata, and route tests fail on Windows path separators.
Review effort: Balanced
Findings: 1
Open (2)
What changed in this PR
Migrates the documentation site from Hugo to Astro while preserving existing routes, content sources, deployment, search, and visual components.
Changes:
- Replaces Hugo layouts with typed Astro pages and components.
- Converts Hugo shortcodes and links to portable Markdown.
- Adds Astro build, formatting, deployment, and built-site regression checks.
| File | Description |
|---|---|
.github/workflows/ci.yml |
Runs Astro validation in CI. |
.github/workflows/docs.yml |
Builds and deploys Astro output. |
.gitignore |
Ignores Astro and npm artifacts. |
README.md |
Documents Astro development commands. |
dev-notes/astro-website.md |
Records migration design and validation. |
website/.prettierignore |
Configures formatting exclusions. |
website/.prettierrc.json |
Enables Astro formatting. |
website/astro.config.mjs |
Configures Astro, sitemap, and callouts. |
website/package.json |
Defines website dependencies and scripts. |
website/package-lock.json |
Locks npm dependencies. |
website/tsconfig.json |
Enables strict Astro TypeScript. |
website/tests/site.test.mjs |
Tests built routes, links, and artifacts. |
website/src/admonitions.mjs |
Transforms Markdown callouts. |
website/src/content.config.ts |
Defines the documentation collection schema. |
website/src/data.ts |
Loads shared site and project data. |
website/src/layouts/Base.astro |
Provides shared metadata and page structure. |
website/src/pages/[...slug].astro |
Generates documentation routes. |
website/src/pages/404.astro |
Implements the Astro error page. |
website/src/pages/index.xml.ts |
Generates the RSS feed. |
website/src/pages/robots.txt.ts |
Generates crawler directives. |
website/src/pages/sitemap.xml.ts |
Preserves the legacy sitemap URL. |
website/src/components/Docs.astro |
Renders documentation navigation. |
website/src/components/Footer.astro |
Ports the site footer. |
website/src/components/Home.astro |
Ports the landing page. |
website/src/components/Navbar.astro |
Ports navigation and search UI. |
website/src/components/Releases.astro |
Renders shared release-note data. |
website/src/components/Roadmap.astro |
Renders roadmap YAML data. |
website/src/components/WhyTau.astro |
Ports the animated Why Tau page. |
website/assets/css/main.css |
Adapts callout styling. |
website/assets/js/nav-toggle.js |
Updates local search instructions. |
website/content/concepts.md |
Converts internal links. |
website/content/contributing.md |
Documents Astro contribution workflow. |
website/content/quickstart.md |
Converts links and callouts. |
website/content/what-is-tau.md |
Converts links and callouts. |
website/content/guides/context.md |
Converts internal links. |
website/content/guides/extensions.md |
Converts internal links. |
website/content/guides/local-inference.md |
Converts internal links. |
website/content/guides/print-mode.md |
Converts links and callouts. |
website/content/guides/project-instructions.md |
Converts links and callouts. |
website/content/guides/project-trust.md |
Converts internal links. |
website/content/guides/providers-and-models.md |
Converts links and callouts. |
website/content/guides/sessions.md |
Converts internal links. |
website/content/guides/skills-and-prompts.md |
Converts callouts. |
website/content/guides/themes.md |
Converts internal links. |
website/content/guides/tui.md |
Converts links and callouts. |
website/content/internals/agent-loop.md |
Converts internal links. |
website/content/internals/architecture.md |
Converts links and callouts. |
website/content/internals/custom-frontend.md |
Converts links and callouts. |
website/content/internals/design-principles.md |
Converts internal links. |
website/content/reference/cli.md |
Converts internal links. |
website/content/reference/configuration.md |
Converts internal links. |
website/content/reference/keybindings.md |
Converts links and callouts. |
website/content/reference/slash-commands.md |
Converts links and callouts. |
website/content/reference/tools.md |
Converts links and callouts. |
website/hugo.toml |
Removes Hugo configuration. |
website/layouts/404.html |
Removes the Hugo error template. |
website/layouts/index.html |
Removes the Hugo landing template. |
website/layouts/doc/single.html |
Removes the Hugo documentation layout. |
website/layouts/_default/baseof.html |
Removes the Hugo base layout. |
website/layouts/_default/releases.html |
Removes the Hugo releases layout. |
website/layouts/_default/roadmap.html |
Removes the Hugo roadmap layout. |
website/layouts/_default/why-tau.html |
Removes the Hugo Why Tau layout. |
website/layouts/partials/admonition.html |
Removes the Hugo callout partial. |
website/layouts/partials/docs-prevnext.html |
Removes Hugo pagination. |
website/layouts/partials/footer.html |
Removes the Hugo footer partial. |
website/layouts/partials/head.html |
Removes the Hugo metadata partial. |
website/layouts/partials/navbar.html |
Removes the Hugo navigation partial. |
website/layouts/partials/sidebar.html |
Removes the Hugo sidebar partial. |
website/layouts/shortcodes/caution.html |
Removes the caution shortcode. |
website/layouts/shortcodes/note.html |
Removes the note shortcode. |
website/layouts/shortcodes/tip.html |
Removes the tip shortcode. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| const route = path | ||
| .relative(path.resolve("content"), file) | ||
| .replace(/\.md$/, "") | ||
| .replace(/(^|\/)\_index$/, ""); |
| import Base from "../layouts/Base.astro"; | ||
| --- | ||
|
|
||
| <Base title="Page not found"> |
paulinebm
added a commit
that referenced
this pull request
Oct 6, 2026
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.
Summary
Migrate the documentation website from Hugo to Astro 7, retaining GitHub Pages hosting at https://twotimespi.dev/.
User experience
Existing bookmarks and heading links continue working. Readers keep the same documentation, search, navigation, and visual identity; contributors gain Astro components, typed metadata, a development server, and automated broken-link checks. No Node dependency is added to Tau's Python runtime.
Related issues
Requested website migration; no dedicated issue to close. Consistent with issue #1's separation of reusable agent packages and presentation layers.
Validation
Local checks passed:
uv run pytest: 2060 passed; 2 Windows/PowerShell-only tests skipped on macOS.uv run ruff check .,uv run ruff format --check .,uv run mypy.npm ci,npm run check(no errors/warnings/hints),npm run format:check,npm run build,npm test(7 tests), andnpm audit(0 vulnerabilities).origin/mainand compared every HTML route and existing element/heading ID: no missing pages or anchors.Manual validation (Node 22.12+):
cd website npm ci npm run build npm run previewOpen http://localhost:4321/:
/index.xml,/sitemap.xml,/robots.txt, installer URLs, and a nonexistent page.Search requires the built index; use preview rather than the development server for search validation. Production deployment remains gated on merge to
main.