Astro Docs Template

Astro Docs Template is a documentation website starter kit built on the Astro framework that turns Markdown and MDX files into a responsive, multi-language docs site with sidebar navigation, Algolia-powered search, and dark mode.

What is Astro Docs Template?

Astro Docs Template is a GitHub template repository (advanced-astro/astro-docs-template) that scaffolds a documentation site with the Astro static site generator. It takes content authored as Markdown (.md) and MDX (.mdx) files placed under src/content/docs/[lang]/ and generates a production static site in ./dist/ when you run pnpm run build. It installs with the command pnpm create astro@latest -- --template advanced-astro/astro-docs-template and starts a local dev server at localhost:3000 via pnpm run dev. The project is maintained by the advanced-astro organization and ships with a default layout (src/layouts/MainLayout.astro) plus a src/config.ts file that centralizes site metadata, sidebar navigation, and language settings.

Key Features

The template bundles a set of documentation-focused features that work out of the box.

• Full Markdown and MDX support — author content in either format and the template renders it as documentation pages.
• Responsive mobile-friendly design — the layout adapts to small screens without extra work.
• Sidebar navigation — controlled by the SIDEBAR object in src/config.ts, organized into section headers and page links.
• Search powered by Algolia — integrates DocSearch; add your API key and index name in src/config.ts and a search box appears in the header.
• Self-hosted webfont (GDPR compliant) — font files are served from your own domain, avoiding third-party requests.
• Multi-language i18n — per-language content folders under src/content/docs/ plus a KNOWN_LANGUAGES map in src/config.ts enable a language switcher.
• Automatic table of contents — generated from page headings with no manual setup.
• Automatic list of contributors — pulls contributor information for each page.
• Dark mode — a built-in toggle that switches the site theme.

Who should use Astro Docs Template?

Astro Docs Template fits anyone who needs a functional documentation site without building a frontend from scratch.

• Open-source maintainers — publish project documentation, API references, and contributing guides from Markdown files without custom frontend code.
• Technical writers — write docs in Markdown or MDX with frontmatter for title and description; the template outputs SEO meta tags and Open Graph data.
• Product teams launching multi-language docs — localize content by adding language directories and updating KNOWN_LANGUAGES in src/config.ts.
• Developers who want a quick docs site — preview instantly with the StackBlitz or CodeSandbox links before committing to a local setup.

Use cases

The template supports several concrete documentation scenarios out of the box.

• Open-source projects: publish API reference and user guides by placing .md files in src/content/docs/en/ and running pnpm run build to generate the static site.
• Multi-language product teams: create Spanish or other translations by duplicating the content folder, adding an entry to KNOWN_LANGUAGES, and updating the sidebar config.
• Indie hackers and startups: launch a documentation site for a SaaS product with dark mode and search, then deploy the dist/ folder to any static host.

How does the template work?

After scaffolding with create astro, you edit src/config.ts to set your project title, description, default language, sidebar entries, and Algolia DocSearch credentials. Content lives as Markdown or MDX files with frontmatter defining the layout and title/description for SEO. Run pnpm run dev to preview locally or pnpm run build to output a static site to dist/, then follow Astro's deployment guides to go live.

FAQ

Does the template support multiple languages?

Yes. The template includes i18n support out of the box: create a new folder under src/content/docs/ for each language and add the language name to KNOWN_LANGUAGES in src/config.ts. The site header then shows a language switcher.

How do I add search to my docs site?

The template integrates Algolia DocSearch. If your project qualifies for DocSearch (free for open-source projects), put your API key and index name in src/config.ts and the search box automatically appears in the header. If you don't use DocSearch, you can remove the Algolia component by editing src/components/Header.astro.

Can I change the accent color?

Yes. The theme's colors are defined as CSS variables in src/styles/theme.scss. The default is a cool blue accent; change the --theme-accent variable to any color you want.

How do I build and deploy the site?

Run pnpm run build from the project root to generate a static site in ./dist/. You can preview the production build locally with pnpm run preview, and deploy the dist/ folder to any static host, such as Netlify or Vercel, using Astro's deployment guides.