Mosona Docs Template

A docs site template built with React + Vite + Tailwind CSS 4. Markdown in, documentation site out — with multi-language support, sidebar navigation, a page TOC, Shiki code highlighting, ⌘K full-text search (Pagefind), dark mode, and "Edit this page" links.

Quick start

pnpm install
pnpm dev

Make it yours

1. config.json (repo root) — the single place to customize:
   • site.name, site.github, site.footerLinks
   • seo.defaultTitle, seo.description, seo.keywords, seo.author, seo.ogImage, seo.ogImageAlt
   • locales + messages (UI strings per locale, incl. all home-page copy)
   • docsGithub — repository/branch/directory for "Edit this page" links
2. docs/ — your Markdown content. index.md is the landing doc at /docs.
3. docs/nav.yaml — sidebar sections and item order. Items are paths relative to the docs root without the .md extension (index = the landing page). Pages not listed appear under an auto-generated "More" section.
4. index.html / public/ — favicon and any static assets. Title and description in index.html are rewritten from config.json at build time. Replace public/og.png (1200×630) with your own social image.
5. LICENSE — replace [Your Name] in the copyright line before you publish a fork.
6. Optional: set VITE_SITE_URL at build time for correct canonical/OG URLs, sitemap.xml, and the Sitemap line in robots.txt.

See CONTRIBUTING.md if you want to change the template itself.

Writing docs

• Default-locale pages live directly under docs/; translations mirror the same paths inside a locale directory (docs/zh-CN/guides/foo.md ↔ docs/guides/foo.md). Missing translations fall back to the original with a language picker card.
• docs/zh-CN/guides/deployment.md is intentionally omitted so the missing-translation fallback is visible out of the box. Add a translation when you no longer want that demo.
• Links ending in .md are rewritten to internal router links.
• Fenced code blocks get Shiki highlighting (light/dark), a copy button, and collapse when longer than 14 lines. Supported languages: src/lib/shiki.ts.
• ##/### headings feed the right-hand table of contents automatically.
• GFM tables, task lists, and raw HTML are supported.

Search

Full-text search is powered by Pagefind and runs entirely client-side against a static index — no server needed:

1. pnpm build pre-renders every default-locale doc page to static HTML inside dist/ (scripts/build-search.mjs), then runs the Pagefind indexer to produce dist/pagefind/.
2. At runtime, the header Search button (or ⌘K / Ctrl+K) queries that index via the Pagefind JS API (src/components/search/docs-search-dialog.tsx).
3. Results link back into the SPA routes via each page's canonical URL.

Search covers all slugs: every page exists in the default locale by design, so the default-locale index is the whole site. In dev mode the dialog explains that search requires a production build. dist/pagefind/ deploys like any other static asset — no host configuration needed.

Alternatives (Algolia DocSearch, a client-side filter over src/lib/docs.ts) can replace this if your project outgrows Pagefind.

Scripts

Script	Purpose
pnpm dev	Dev server
pnpm build	Type-check + production build + Pagefind index
pnpm preview	Preview the production build
pnpm check	Biome lint + format check
pnpm fix	Biome autofix
pnpm test	Unit tests
pnpm test:watch	Unit tests in watch mode
pnpm typecheck	tsc --noEmit

Deployment

The build output is a static SPA in dist/. Serve it from any static host with an SPA fallback (all routes → index.html). See docs/guides/deployment.md.

Project structure

├── config.json            # Site identity, locales, messages, SEO, docs GitHub
├── docs/                  # Your Markdown content + nav.yaml
│   └── <locale>/          # Translations mirroring default-locale paths
├── public/                # Static assets (favicon, og.png, robots.txt)
├── scripts/
│   └── build-search.mjs   # Prerenders docs HTML + runs Pagefind (post-build)
└── src/
    ├── components/
    │   ├── docs/          # Sidebar, mobile nav, TOC, markdown renderer,
    │   │                  # collapsible code block, missing-translation card
    │   ├── search/        # ⌘K search dialog (Pagefind JS API)
    │   └── ui/            # Button (shadcn-style)
    ├── hooks/             # usePageSeo
    ├── lib/
    │   ├── docs.ts        # Loads docs/, parses slugs/headings, builds nav
    │   ├── i18n.ts        # Locale detection & messages (from config.json)
    │   ├── seo.ts         # Per-page meta tags
    │   └── shiki.ts       # Code highlighting config
    ├── pages/             # Home page, docs page, 404
    └── search/            # prerender-docs.tsx (Pagefind index source)

License

MIT — see LICENSE.