Skip to content

chore: cut over docs to fumadocs (phase 7)#127

Merged
pratyush618 merged 1 commit intomasterfrom
chore/docs-cutover
May 2, 2026
Merged

chore: cut over docs to fumadocs (phase 7)#127
pratyush618 merged 1 commit intomasterfrom
chore/docs-cutover

Conversation

@pratyush618
Copy link
Copy Markdown
Collaborator

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 --follow works through the rename).
  • zensical.toml deleted — config file for the old generator, gone.
  • Old docs/ deleted — 103 markdown files (the Zensical content). Everything was already ported to MDX in phases 2–4.

Workflows

  • .github/workflows/docs.yml rewritten — replaces the Zensical build (uv run zensical buildactions/upload-pages-artifact) with a pnpm + Next.js flow that runs types:check, lint, and build on every PR (path-filtered to docs/**), and on push-to-master uploads docs/out/ and deploys via actions/deploy-pages@v5. Same Pages source ("GitHub Actions"), same custom domain (docs.byteveda.org), no DNS changes needed.
  • .github/workflows/docs-next.yml deleted — temporary CI was scoped to PRs only; folded into the new docs.yml so we have a single source of truth.

Other repo updates

  • pyproject.toml — removed the docs = ["zensical"] extra; fixed Changelog URL (was pointing at docs/changelog.md, would 404 after the delete; now points at https://docs.byteveda.org/taskito/docs/more/changelog).
  • README.md — replaced taskito.grigori.in (stale personal domain) with docs.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 the pip install ".[docs]" + zensical serve block 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

  • DNS / CNAMEdocs.byteveda.org already 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.
  • GitHub Pages settings — already set to "GitHub Actions" as source. No changes needed in repo settings.

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/changelog

External 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 — clean
  • pnpm --dir docs lint — exit 0 (2 known scaffold-CSS warnings)
  • pnpm --dir docs build — clean static export to docs/out/
  • grep -rn "docs-next\|zensical\|grigori\.in" across repo — empty (only docs: commit-type mention in semantic-pr.yml remains, which is correct)
  • CI on this PR: Deploy Docs job runs types:check + lint + build against the renamed docs/ path
  • Manual smoke after merge: visit https://docs.byteveda.org/taskito — should show the new Fumadocs landing
  • Manual smoke: hit https://docs.byteveda.org/taskito/llms.txt — should return the IA index

Phases summary (full migration arc)

Phase PR What
1 #110#111 Scaffold (Docusaurus first, then Fumadocs after the GH-Pages re-evaluation)
2 #113 Port Home + Getting Started + Architecture
3 #115 Port API Reference
4 a–j #116#125 Port all 71 guide / integrations / examples pages
5 #126 Landing page polish
6 (built into Fumadocs scaffold — /llms.txt, /llms-full.txt, /raw/... routes shipped from day one)
7 this PR Cutover

After merge, v0.12 is shippable. Tag + PyPI/crates.io publish are deliberate manual steps.

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.
@pratyush618 pratyush618 merged commit 48c671a into master May 2, 2026
22 checks passed
@pratyush618 pratyush618 deleted the chore/docs-cutover branch May 3, 2026 04:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant