Astro文档

compass — Astro 文档模板

作者 xocothemes

基于 Astro 7 与 Tailwind CSS 4 的文档模板，用 MDX 内容集合和 Pagefind 搜索搭建产品文档与知识库。

打开源站下载源码 ZIP

看看你的网站会是什么样

浏览真实页面截图，比较内容排版与手机效果。点击下方缩略图切换，放大查看整页细节。

3 个预览视图

桌面端首页1 / 3

访问演示网站在新标签页打开

桌面端截图

演示站首页的真实桌面布局。

全部页面与视图 3

截图用于了解视觉与布局，交互效果请以实际项目为准。本截图因高度限制未包含整页。

采集于 2026-09-27查看来源

值得关注的模板亮点

从已有项目资料中，快速了解它的特点。

Astro 7 + Tailwind CSS 4 + TypeScript，不依赖重量级文档框架

MDX 内容集合，每篇文章一个文件夹，图片与文章同目录

分类配置集中在 src/data/docs.ts，驱动首页、侧边栏与嵌套路由

Pagefind 构建时搜索，覆盖文档首页与侧边栏

内置 Callout、Tabs、CodeTabs、FileTree、Steps、Checklist 等 MDX 组件

frontmatter 支持 status、redirectFrom、hideFromSearch、relatedLinks 等字段

模板详细介绍

Compass 是一个面向产品文档、支持中心和内部知识库的 Astro 文档模板，走的是轻量路线——不引入重量级文档框架，而是用 Astro 7、Tailwind CSS 4 和 MDX 内容集合自己组织内容。导航结构由分类驱动，配合可复用的 MDX 组件和明暗主题，整体观感偏干净克制。

内容组织方式比较有辨识度：每篇文章独占一个文件夹，MDX 文件与 slug 同名，图片等资源放在文章旁边，交给 Astro 的图片管线处理。分类定义集中在 src/data/docs.ts，同时驱动首页卡片、侧边栏导航和嵌套路由生成，URL 固定为 /:parent/:category/:slug 三层结构。文章 frontmatter 支持 tags、status、editUrl、heroImage、redirectFrom、hideFromSearch 等字段，其中 draft 和 archived 状态的文章会从路由、导航、搜索、重定向和 RSS 中排除。搜索由 Pagefind 在构建时生成，另有可选的 /rss.xml 订阅源。

适合已经熟悉 Astro 或愿意接受 MDX 写作流程的团队，用来快速起一个结构清晰的文档站。需要注意几点：搜索只在 npm run build 后生成，本地要跑 npm run preview 才能验证完整搜索体验；site.config.mjs 里默认仍是占位 URL，发布前必须替换；单段式子分类 URL（如 /start-here）不会生成也不默认重定向。仓库标称 MIT 许可，但资料中许可状态标注为 review，正式使用前建议自行核对 LICENSE 文件。

Astro文档

适合你的项目吗？

适用场景

产品文档站：按父级、子分类、文章三层组织内容
支持中心或帮助中心：用分类导航和搜索引导用户查找答案
内部知识库：以 MDX 写作、按状态管理草稿与归档内容
需要代码示例的技术文档：CodeTabs 与 FileTree 组件适合命令和仓库结构说明

适合人群

熟悉 Astro 或 MDX 写作流程的开发者与文档团队
希望用仓库模板方式起步、自行替换示例内容与品牌的团队
需要静态站点、构建时搜索和 RSS 的文档项目

上手与定制指南

结合仓库当前版本的说明，按下面的资料检查内容、配置与运行要求。

1
通过 GitHub 的 Use this template 复制仓库，再执行 npm install 与 npm run dev
2
发布前替换 site.config.mjs 中的 siteUrl、name、title、description、githubUrl、navCtaLabel、navCtaHref、footerText 等占位值
3
搜索在 npm run build 时生成，本地验证完整搜索需使用 npm run preview
4
文章 frontmatter 的 category 必须匹配 src/data/docs.ts 中已定义的分类 slug，否则 npm run check 会报内容校验错误
5
单段式子分类 URL 不会生成，也不默认重定向；重命名或移动文档需通过 redirectFrom 配置别名

查看仓库使用说明