Hugo migration

[kristin-kronstain-brown]

Migrate docs to Hugo, build marketing + docs together

Summary

Migrates the kagent/kmcp documentation from Next.js MDX to a Hugo + Hextra + docs-theme-extras site, and wires it into the existing Next.js marketing app so both build and deploy as one Cloudflare Worker, one origin. The docs are served as static assets under /docs/*; the marketing site (home, blog, tools, agents, community, enterprise) stays on Next.js. Also unifies the top navbar so the marketing and docs pages look consistent.

Architecture

• Monorepo layout. The Hugo docs site lives in docs-site/, alongside the Next.js app. The subdirectory sidesteps the package.json/go.mod collision that previously required a separate branch.
• Docs served under /docs. Hugo's baseURL carries the /docs prefix and content lives at content/<product>/, so Hugo emits a self-contained tree (pages + css/js/images/favicons) that drops into the worker's static assets with no collisions against the marketing site's /images, sitemap.xml, etc.
• Combined build via make. make build builds the Hugo docs, injects the output into public/docs/ (preserving tracked assets like versions/), then builds the opennextjs worker. Cloudflare Workers Assets serve /docs/* (static Hugo) before the worker runs, so the marketing worker handles everything else. Verified end-to-end with wrangler dev.

What's included

Docs site (docs-site/)

• Full Hugo site: hugo.yaml, layouts, assets, content/kagent/** and content/kmcp/** (234 pages), Tailwind/PostCSS pipeline.
• Project overrides: sidebar rooted per-product via .FirstSection; navbar-link.html for a Docs dropdown (kagent/kMCP with product icons) and uniform link styling; logo links to the marketing home (/).

Converter (scripts/mdx-to-hugo.mjs)

• Idempotent MDX→Hugo converter (run via make gen-docs). Handles frontmatter merge, component→shortcode mapping (Tabs, Aside, FeatureGrid, Mermaid, QuickLink), version placeholders, link rewrites, and unwraps the 'use client' React-component wrapper (kmcp landing).

Build tooling

• Root Makefile (build-docs, inject-docs, build-web, build, preview, deploy, serve-docs, gen-docs, clean). preview builds docs with a localhost baseURL so internal links stay local.
• .gitignore updated for docs build artifacts and injected public/docs.

Navbar unification

• Rewrote src/components/navbar.tsx to mirror the Hextra docs nav (order, uniform gray links, Docs dropdown with icons, GitHub icon, search, borderless theme toggle) in light and dark mode.
• Decoupled /tools and /agents from the old docs layout (removed their layout.tsx) so they render as standalone marketing pages.

Fixes

• Dropdown spacing/alignment, logo light/dark switch, and navbar dark-mode background handled in custom.css (Hextra's prebuilt CSS omits some hx: utilities).
• Fixed a real source bug in the release-notes MDX (new-svc-tab panel id).

Editing the docs

docs-site/content/ is the source of truth — author docs there directly; the converter is only for re-migrating from the legacy src/app/docs MDX, not the normal workflow.

• Edit / add pages: docs-site/content/kagent/** and docs-site/content/kmcp/** (Markdown with Hugo frontmatter). A leaf page is <name>.md; a section with children is a folder with _index.md. Ordering is weight in frontmatter; the sidebar and section cards are generated automatically.
• Shortcodes: use the docs-theme-extras/Hextra shortcodes natively ({{< tabs >}}, {{< callout >}}, {{< cards >}}, etc.).
• Nav / dropdown / menu: edit docs-site/hugo.yaml (menu.main). Same-origin marketing links use params.localHref; docs products use url: /<product>.
• Styling: put custom CSS in docs-site/assets/css/custom.css (don't rely on ad-hoc hx: Tailwind utilities — many aren't generated in this build).
• Re-migrating from MDX (rare): make gen-docs regenerates docs-site/content from src/app/docs. Diff before committing so hand edits aren't lost.

Previewing locally

First-time setup (installs web + docs deps and Hugo modules):

make install

Marketing + docs together — the real combined site (builds everything, serves via wrangler dev) at http://localhost:3000:

make preview

This is where to confirm /docs/* routing, cross-links between marketing and docs, and the unified navbar.

Notes:

• In make serve-web/next dev, /docs falls back to the old Next route (no Cloudflare asset layer locally); use make preview to see the real Hugo docs.
• If a page looks stale or shows the old nav, check for a leftover wrangler dev (workerd) still bound to port 3000 from a prior make preview — pkill -f wrangler and restart.

Follow-ups

• Old src/app/docs kept (shadowed by the Hugo docs at the edge); removable later once generate-nav/check-links are trimmed.
• CI preview (.github/workflows/preview.yaml) still runs npm run build:worker; needs Hugo/Go setup + make build to include docs in PR previews.

Testing

• Hugo build clean (234 pages, no leaks), link check 474 links / 0 broken.
• Combined make build green; docs bundled into worker assets.
• wrangler dev confirmed / → Next, /docs/* → Hugo.
• Navbar verified light + dark against the docs nav.

[Rachael-Graham]

duplicates the description

[kristin-kronstain-brown]

Fixed

[Rachael-Graham]

i think cards on any _index.md file would need to be removed

[kristin-kronstain-brown]

Fixed