ZueDocs

zuedocs is a reusable Astro docs shell for product docs sites.

It gives you a shared presentation layer for:

• landing pages
• docs index pages
• docs article pages with sidebar and table of contents
• shared styles
• client-side docs enhancements like copy buttons, page action menus, Mermaid rendering, and responsive table wrappers

The intended model is:

1. keep shared docs UI in zuedocs
2. publish it to npm
3. let downstream docs repos consume it as a dependency
4. keep repo-specific content and branding local

What stays local in each docs repo

Each consuming repo should keep these pieces in its own codebase:

• markdown docs content
• src/data/docs.ts
• homepage and product copy
• repo-specific Astro and deployment config

src/data/docs.ts is the seam between the shared shell and the local site. At a high level it defines:

• siteConfig
• primaryNav
• docCategories

Package surface

zuedocs currently exports:

• zuedocs/layouts/BaseLayout.astro
• zuedocs/layouts/DocsPageLayout.astro
• zuedocs/components/SiteHeader.astro
• zuedocs/components/ThemeToggle.astro
• zuedocs/components/SiteFooter.astro
• zuedocs/components/DocsPageActions.astro
• zuedocs/docsEnhancements
• zuedocs/styles.css
• zuedocs/types

The exported types currently include:

• SiteConfig
• PrimaryNavItem
• FooterSection

SiteConfig supports:

• name
• strapline
• description
• repoUrl
• optional footerSections

Scaffold a new docs site

Use the scaffold CLI when you want a brand new docs app with the shared shell already wired in.

Preferred command:

bunx zuedocs init my-docs

Alias form:

bunx --package zuedocs create-zuedocs my-docs

Do not use plain bunx create-zuedocs my-docs. create-zuedocs is a bin inside the zuedocs package, not a standalone npm package.

Important behavior

zuedocs init requires an empty target directory. It is a scaffold command, not an in-place migration tool.

That means:

• good: bunx zuedocs init docs-site
• bad: running it at the root of an existing non-empty repo

Existing project pattern

If you already have an application repo, create a docs subdirectory instead of trying to scaffold over the root.

Example:

my-project/
  app/
  internal/
  package.json or go.mod
  docs-site/

Recommended flow:

bunx zuedocs init docs-site
cd docs-site
bun install
bun run check
bun run build

Then customize:

• src/data/docs.ts
• src/pages/index.astro
• src/content/docs/*.md

Use it inside an existing Astro docs site

If you already have an Astro docs site and only want the shared shell, install the package and wire it in manually.

Install:

bun add -d zuedocs

Example:

---
import BaseLayout from "zuedocs/layouts/BaseLayout.astro";
import DocsPageLayout from "zuedocs/layouts/DocsPageLayout.astro";
import { primaryNav, siteConfig } from "../data/docs";
---

<BaseLayout
  title={`${siteConfig.name} | ${siteConfig.strapline}`}
  description={siteConfig.description}
  siteConfig={siteConfig}
  primaryNav={primaryNav}
>
  <DocsPageLayout
    title="Guide title"
    description="Guide summary"
    category="Start"
  >
    <p>Your docs content.</p>
  </DocsPageLayout>
</BaseLayout>

<script>
  import "zuedocs/docsEnhancements";
</script>

Example docs.ts

export const siteConfig = {
  name: "My Product",
  strapline: "Documentation",
  description: "Docs for My Product.",
  repoUrl: "https://github.com/my-org/my-product",
  footerSections: [
    {
      title: "My Product",
      text: "Short footer description for the docs site."
    },
    {
      title: "Repository",
      linkPrefix: "Source: ",
      linkHref: "https://github.com/my-org/my-product",
      linkLabel: "github.com/my-org/my-product"
    }
  ]
} as const;

export const docCategories = ["Start", "Guides", "Operations"] as const;

export const primaryNav = [
  { href: "/", label: "Overview" },
  { href: "/docs", label: "Docs" },
  { href: siteConfig.repoUrl, label: "GitHub", external: true }
];

Local development

For this repo:

bun install
bun run dev

Validation:

bun run check
bun run build

Page action menu

Docs pages include a compact action menu at the top of the page. It can copy the current page from the raw Markdown endpoint, open that .md endpoint in a new tab, and open common AI chat tools with a prefilled prompt pointing at the page.

For example, /docs/quickstart resolves its raw source as /docs/quickstart.md, and /docs resolves as /docs.md.

Theme toggle

SiteHeader.astro includes a small theme toggle after the primary navigation. It cycles between system, light, and dark, stores the selection in local storage, and applies the resolved theme before paint from BaseLayout.astro to avoid a light/dark flash. The toggle is enabled by default and can be disabled with themeToggle: false in siteConfig.

Raw markdown routes

The docs routes also expose raw markdown endpoints.

Examples:

• /docs.md
• /docs/quickstart.md
• /docs/deployment.md

This is useful when another tool or agent wants the source markdown instead of rendered HTML.

Release model

zuedocs is designed to be published and consumed as a versioned dependency.

Release flow:

1. push a change to main
2. GitHub Actions validates the package
3. GitHub Actions bumps package.json by one patch version
4. GitHub Actions creates a release commit and tag like v0.1.7
5. GitHub Actions publishes that version to npm
6. downstream repos update via Renovate or manual dependency bumps

Every non-bot push to main produces a new patch release automatically. This keeps shared docs UI centralized instead of copied across repos.