logo
English

导航菜单

Introduction to Astro

Build a Documentation Site with Astro

Recommended project structure

  • src/pages: Docs pages (Markdown/MDX).
  • src/layouts: Docs layouts (nav, sidebar, footer, version switch).
  • src/content: Content collections and frontmatter validation.
  • src/components: Reusable UI (nav, TOC, callouts, cards).

Sidebar and navigation

  • Data-driven: const nav = [{ title, slug, items: [...] }].
  • Render sidebar in layout and highlight current path.
  • Top nav hosts search, theme switch, version switch.

Markdown + MDX

  • Write prose in Markdown; embed interactive demos with MDX.
  • Import components at top of MDX and map tags via export const components.
  • Use callouts (info/success/warning) for key notes.

Code samples and highlighting

  • Use fenced code blocks (```js/ts etc.), enable line numbers/highlight if needed.
  • Offer copy buttons or demo links.
  • For multi-framework snippets, provide tabbed variants (React/Vue/Svelte).

Search and TOC

  • Generate a static index JSON at build time; use Fuse.js/Lunr on the client.
  • Build a page-level TOC from headings and place it in the sidebar or a floating panel.

Deployment and preview

  • pnpm build outputs a static site for CF Pages/Netlify/Vercel.
  • Use preview environments for content QA and link checking.

Common issues

  • 404s: check route casing, path prefixes, site base.
  • Missing highlight: confirm theme or Shiki/Prism config.
  • TOC not updating: keep heading levels consistent (no skips).

Astro is ideal for docs because:

  1. Performance-first: zero-JS-by-default keeps docs blazing fast.
  2. Markdown-first: native Markdown/MDX support makes writing easy.
  3. Content collections: built-in schema/collections fit large doc sets.
  4. SEO-friendly: static output is easily indexed.

Create a docs project

1. Initialize

npm create astro@latest my-docs

During setup:

  • Pick the “Empty” template.
  • Choose TypeScript if you want it.
  • Install dependencies.

2. Add a docs theme

Astro has solid docs themes; for example, the official Starlight:

npx astro add @astrojs/starlight

3. Configure the docs structure

astro.config.mjs example:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      description: 'Project documentation site',
      defaultLocale: 'en',
      locales: {
        en: { label: 'English', lang: 'en' },
      },
      sidebar: [
        {
          label: 'Getting Started',
          items: [
            { label: 'Introduction', link: '/' },
            { label: 'Quickstart', link: '/getting-started' },
          ],
        },
      ],
    }),
  ],
});

Organize content

1. Create doc pages

src/content/docs/quickstart.md:

---
title: Quickstart
description: Get started with the product
---

# Quickstart

Welcome to our product...

2. Wire up navigation

  • Use frontmatter for metadata.
  • Configure sidebar hierarchy.
  • Add an auto-generated TOC.

3. Add base styles

src/styles/custom.css:

:root {
  --sl-color-accent: #00539F;
  --sl-color-accent-low: #E1E6F6;
}

Enhance the docs

Starlight ships search; tune it as needed:

starlight({
  // ...
  search: {
    indexLocales: true,
    searchOptions: {
      includeFuzzy: true,
    },
  },
});

2. Versioning

Separate versions by folder/branch:

src/content/docs/
  ├── v1/
  │   └── guide.md
  └── v2/
      └── guide.md

3. Custom components

Reusable components for docs:

---
// src/components/Tutorial.astro
---
<div class="tutorial">
  <slot />
</div>

<style>
.tutorial {
  padding: 1rem;
  border: 1px solid var(--sl-color-gray-5);
  border-radius: 0.5rem;
}
</style>

Best practices

  1. Structure

    • Keep a clear folder hierarchy.
    • Keep navigation shallow and consistent.
    • Add meaningful metadata to every page.

  2. Content

    • Maintain a consistent voice.
    • Include useful code samples.
    • Add helpful images/diagrams.

  3. Performance

    • Optimize images.
    • Use client components sparingly.
    • Keep page load fast.

Next steps

After the basic docs site works, you can:

  1. Add custom styling.
  2. Integrate comments.
  3. Add i18n.
  4. Set up automatic deploys.

With these steps, you can build a full-featured docs site in Astro. Next chapters can cover deeper content management and theming details.

PreviousComponents and PagesDeep dive into Astro components and page building NextContent Management and Theme CustomizationManage docs content and theme customization in Astro

搜索