Skip to content

feat(docs): scaffold docusaurus next site (phase 1)#110

Closed
pratyush618 wants to merge 2 commits intomasterfrom
feat/docs-docusaurus-scaffold
Closed

feat(docs): scaffold docusaurus next site (phase 1)#110
pratyush618 wants to merge 2 commits intomasterfrom
feat/docs-docusaurus-scaffold

Conversation

@pratyush618
Copy link
Copy Markdown
Collaborator

First phase of the docs migration off Zensical. Sets up docs-next/ (Docusaurus 3.10.1 + TypeScript) alongside the existing Zensical site. The Zensical site at docs.byteveda.org/taskito keeps shipping unchanged; nothing is removed or repointed in this PR.

What's in here

docs-next/ — Docusaurus 3.10.1 scaffold customised for Taskito:

  • Title / tagline / favicon / GitHub edit URL
  • url: https://docs.byteveda.org, baseUrl: /taskito/ (so cutover preserves existing URLs)
  • colorMode.defaultMode: dark (matches the brand)
  • Blog disabled (blog: false) — we're docs-only
  • 5 sidebars: gettingStartedSidebar / guidesSidebar / architectureSidebar / apiReferenceSidebar / moreSidebar — all autogenerated from folder layout
  • Navbar: 5 top-level docSidebar links + a More dropdown (Examples / Comparison / FAQ / Changelog) + GitHub icon
  • markdown.hooks.onBrokenMarkdownLinks: 'throw' (Docusaurus v4-ready shape; the deprecated top-level field is gone)
  • Prism additionalLanguages: rust, toml, bash, yaml, json, python

IA skeleton (33 files, all stubs that say "Phase 1 stub — content port pending"):

  • getting-started/ × 3 (installation, quickstart, concepts)
  • guides/ × 9 sub-categories (core, reliability, advanced-execution, operations, observability, resources, workflows, integrations, extensibility) — folds in three formerly-top-level Zensical sections (Resources, Workflows, Integrations) per the approved IA
  • architecture/overview.mdx
  • api-reference/overview.mdx
  • more/ × 4 (examples, comparison, faq, changelog) — collapses Zensical's awkward "Changelog" + "Changelog Archive" split

Landing page — minimal Taskito version of src/pages/index.tsx and HomepageFeatures (3 cards: Brokerless / Rust-powered / Python-native). Phase 5 does the real visual polish.

.github/workflows/docs-next.yml — build + typecheck on PR (path-filtered to docs-next/**). No deploy step yet — cutover lives in phase 7.

What's NOT in here (next phases)

  • Content port (phases 2–4) — actual prose moved from docs/ into the stubs
  • API reference component (<APIMethod> — phase 3)
  • Landing page polish + shadcn-style components (phase 5)
  • LLM-friendly routes (/llms.txt, /raw/[...slug] — phase 6)
  • Hosting / DNS cutover and Zensical decommission (phase 7)

Test plan

  • pnpm install --frozen-lockfile — clean
  • pnpm typecheck (i.e. tsc) — clean
  • pnpm build[SUCCESS] Generated static files in "build", zero warnings
  • git status --untracked-files=all after install — node_modules / build / .docusaurus all stay out of the index (Docusaurus's own .gitignore handles them)
  • CI: new Build Docs (Next) job passes on this PR
  • Manual smoke once merged: spin up pnpm --dir docs-next start locally and confirm all 6 nav buckets resolve, the dropdown opens, dark mode is default

Brings up `docs-next/` (Docusaurus 3.10.1 + TypeScript) alongside the
existing Zensical site. Six top-level sections, five sidebars, IA
skeleton stubs only — content port and cutover are later phases.
Catches build breaks in the new docusaurus site before merge.
No deploy step yet — cutover lives in phase 7.
@pratyush618
Copy link
Copy Markdown
Collaborator Author

Switching to Fumadocs after revisiting the GH Pages constraint — Next.js static export works fine and the LLM-readability + MDX-with-shadcn wins are worth the swap. Replacement PR coming.

@pratyush618 pratyush618 closed this May 2, 2026
@pratyush618 pratyush618 deleted the feat/docs-docusaurus-scaffold branch May 2, 2026 19:21
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