Docs Template

A NukeHub-first documentation template built with plain Astro + React + Tailwind CSS v4. No Starlight, no chrome clashes — every pixel of the header, footer, sidebar, search, and theme is custom and reusable.

What this template is

This repository is a reusable template for documentation sites in the NukeHub ecosystem. It replaces Starlight with a small set of custom components while keeping the content workflow the same:

• Write docs in Markdown/MDX under docs/ in the repo root.
• Run npm run sync-docs to copy and clean them into src/content/docs/.
• Build a static site ready for GitHub Pages.

How to use this template for a new project

1. Click Use this template on GitHub and create a new repository.

2. Clone the new repository.

3. Install dependencies:

   npm install

4. Update project identity in src/data/site.ts:

   export const SITE = {
     name: "Your Project",
     logoText: "Your Project",
     description: "A short description.",
     site: "https://your-org.github.io",
     base: "/your-repo",
     github: "https://github.com/your-org/your-repo",
     editBranch: "main",
     editPath: "docs/",
   };

   The base value must match your GitHub repository name.

5. Add your own documentation under docs/ in the repo root.

6. Run npm run dev to preview locally.

7. Push to main; the GitHub Actions workflow in .github/workflows/deploy.yml publishes to Pages.

Customizing identity, nav, and footer

File	Purpose
src/data/site.ts	Site name, description, base path, GitHub URLs.
src/data/nav.ts	Header navigation items.
src/data/footer.ts	Footer link columns.

Update these three files to rebrand the site for any project.

Adding documentation

Create files under docs/:

docs/
├── README.md          # Becomes the home page
├── tutorials/
│   └── getting-started.md
├── reference/
│   └── index.md
├── development/
│   └── local-dev.md
└── architecture/
    └── overview.md

Each page supports this frontmatter:

---
title: Page Title
description: A short description.
sidebar:
  label: Short label
  order: 1
draft: false
---

The root README.md is renamed to index.md automatically, and internal .md links are rewritten to clean trailing-slash routes.

Development scripts

Script	Purpose
npm run dev	Sync docs and start the dev server.
npm run build	Sync docs and build the static site.
npm run preview	Preview the built site.
npm run check	Run Astro type checks.
npm run lint	Run ESLint.
npm run format	Format files with Prettier.
npm run format:check	Check formatting without writing.

MDX shortcodes

Pages written as .mdx can use these components without importing them:

<Callout type="tip" title="Tip">
  Use `npm run sync-docs` before building to refresh content.
</Callout>

<Tabs defaultValue="npm">
  <TabItem value="npm" label="npm">
    npm install
  </TabItem>
  <TabItem value="pnpm" label="pnpm">
    pnpm install
  </TabItem>
</Tabs>

<FileTree items={[{ name: "docs", children: [{ name: "README.md" }] }]} />

<Mermaid chart={`flowchart LR; A --> B`} />

<Steps>
  <Step>Do this first.</Step>
  <Step>Then do this.</Step>
</Steps>

<YouTube id="dQw4w9WgXcQ" title="Getting started" />

<ImageFigure src="/docs-template/screenshot.png" alt="Screenshot" caption="Docs template" />

<DataTable
  columns={[{ key: "name", header: "Name" }]}
  data={[{ name: "U-235" }]}
  sortable
  searchable
/>

Supported types for <Callout>: info, note, warning, tip, success, danger.

Code blocks in Markdown and MDX automatically get a copy button.

Project structure

src/
├── components/
│   ├── layout/      # Header, Footer, Sidebar, BaseLayout, DocLayout
│   ├── shared/      # Command palette, theme toggle, search, scroll progress, context menu, lightbox
│   ├── ui/          # Button, Card, Tooltip, Logo, Input, Image
│   ├── docs/        # TOC, Pagination, EditLink
│   └── mdx/         # Callout, Tabs, TabItem, FileTree, Mermaid, Steps, YouTube, Odysee, ImageFigure, DataTable shortcodes
├── content/         # Synced docs content
├── data/            # site.ts, nav.ts, footer.ts
├── lib/             # utils.ts, theme.ts, docs.ts
├── pages/
│   └── [...slug].astro
└── styles/
    └── global.css

Deployment

The included .github/workflows/deploy.yml builds and deploys to GitHub Pages on every push to main. Make sure the repository Pages source is set to GitHub Actions.

Markdown content negotiation

Every built HTML page also gets a Markdown sibling. For example, /tutorials/getting-started/ has a matching /tutorials/getting-started/index.md.

• Direct .md URLs serve the Markdown file.
• public/_worker.js enables Accept: text/markdown content negotiation on hosts that support Cloudflare Pages advanced-mode Workers.
• GitHub Pages serves the generated .md files statically, but cannot negotiate by Accept header.

Design notes

• The theme engine stores the preference in localStorage under docs-theme and applies it via data-theme on <html>.
• The command palette indexes doc titles, descriptions, and categories; open it with Cmd/Ctrl+K.
• Right-click anywhere to open a custom context menu with search, copy, and navigation.
• The sidebar is generated from the synced docs file tree.
• A scroll-progress bar appears at the top of doc pages.
• Code blocks get an automatic copy button.
• No @astrojs/starlight dependency is included.

License

BSD-2-Clause — see the LICENSE file.