chore: cut over docs to fumadocs (phase 7)#127
Merged
pratyush618 merged 1 commit intomasterfrom May 2, 2026
Merged
Conversation
Replaces the Zensical site at `docs/` with the Fumadocs site previously built at `docs-next/`, deletes `zensical.toml`, rewrites `.github/workflows/docs.yml` to build pnpm + Next.js static export from `docs/out` and deploy to GitHub Pages, and folds the temporary `docs-next.yml` into the cutover workflow. Updates README, CONTRIBUTING, CLAUDE.md, pyproject Changelog URL, and `.claude/memory/docs.md` for the new stack and paths.
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.
Phase 7 of the docs migration. Final PR before v0.12 ships. Replaces the Zensical site with the Fumadocs site, decommissions Zensical entirely, and updates every doc-build reference across the repo.
What this PR does
Cutover
docs-next/→docs/— git-mv'd in place so the new Fumadocs site lives where the old Zensical site lived. History preserved on every file (git log --followworks through the rename).zensical.tomldeleted — config file for the old generator, gone.docs/deleted — 103 markdown files (the Zensical content). Everything was already ported to MDX in phases 2–4.Workflows
.github/workflows/docs.ymlrewritten — replaces the Zensical build (uv run zensical build→actions/upload-pages-artifact) with a pnpm + Next.js flow that runstypes:check,lint, andbuildon every PR (path-filtered todocs/**), and on push-to-master uploadsdocs/out/and deploys viaactions/deploy-pages@v5. Same Pages source ("GitHub Actions"), same custom domain (docs.byteveda.org), no DNS changes needed..github/workflows/docs-next.ymldeleted — temporary CI was scoped to PRs only; folded into the newdocs.ymlso we have a single source of truth.Other repo updates
pyproject.toml— removed thedocs = ["zensical"]extra; fixed Changelog URL (was pointing atdocs/changelog.md, would 404 after the delete; now points athttps://docs.byteveda.org/taskito/docs/more/changelog).README.md— replacedtaskito.grigori.in(stale personal domain) withdocs.byteveda.org/taskito; updated in-text doc paths to the new IA (/guide/execution/prefork/→/docs/guides/advanced-execution/prefork); cleaned up "crossbeam" → "tokio mpsc" reference (the migration to tokio happened way back; the README hadn't caught up).CLAUDE.md— refreshed test counts (77→89 Rust, 469→496 Python, 46→49 test files), added a docs build block (pnpm --dir docs ...).CONTRIBUTING.md— replaced thepip install ".[docs]" + zensical serveblock with the Fumadocs equivalent (pnpm --dir docs install + dev)..claude/memory/docs.md— full rewrite for Fumadocs conventions (stack, IA, MDX patterns, custom components, gotchas).What does NOT change
docs.byteveda.orgalready CNAMEs to GitHub Pages. The new workflow uses the same publish mechanism (upload-pages-artifact+deploy-pages), so the artifact swaps in place.basePath: '/taskito'— already lined up with the GH Pages path prefix; production builds emit URLs that match the existing CNAME mapping.Known SEO/UX cost (intentional)
URL paths change from the Zensical layout to the Fumadocs IA. Examples:
/guide/execution/prefork/→/docs/guides/advanced-execution/prefork/api/queue/→/docs/api-reference/queue/changelog/→/docs/more/changelogExternal inbound links (PyPI page, blogs, Stack Overflow answers) will 404 until they're updated. Server-side redirects aren't possible on static GitHub Pages. This was flagged as a non-goal in the original migration plan.
Test plan
pnpm --dir docs types:check— cleanpnpm --dir docs lint— exit 0 (2 known scaffold-CSS warnings)pnpm --dir docs build— clean static export todocs/out/grep -rn "docs-next\|zensical\|grigori\.in"across repo — empty (onlydocs:commit-type mention insemantic-pr.ymlremains, which is correct)Deploy Docsjob runstypes:check + lint + buildagainst the renameddocs/pathhttps://docs.byteveda.org/taskito— should show the new Fumadocs landinghttps://docs.byteveda.org/taskito/llms.txt— should return the IA indexPhases summary (full migration arc)
/llms.txt,/llms-full.txt,/raw/...routes shipped from day one)After merge, v0.12 is shippable. Tag + PyPI/crates.io publish are deliberate manual steps.