mosona-docs — Vite 文档模板

SHA-256: 9dc9cba47e5cd6f23b2cc6bbb372e0633f3ec787dd97306f579a36b3b2be7af5

2026-10-18T00:23:26.040Z

# Mosona Docs Template

<img width="49.5%" alt="md1" src="https://github.com/user-attachments/assets/2e0b4617-fd20-4a77-b7dc-6489d39d47a0" />
<img width="49.5%" alt="md2" src="https://github.com/user-attachments/assets/3bce5c99-fc8a-44d6-b979-83d135f853c9" />

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

```bash
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](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](https://pagefind.app/) 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 <kbd>⌘K</kbd> / <kbd>Ctrl</kbd>+<kbd>K</kbd>) 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](docs/guides/deployment.md).

## Project structure

```text
├── 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](LICENSE).