ReallySimpleDocs
一个面向 Astro 的简单文档系统,使用 Basecoat 和 Tailwind CSS 构建。
ReallySimpleDocs 让文档保持可移植:内容放在 docs/,导航放在 docs/docs.json,由 Astro 集成负责文档 UI、搜索、Markdown 导出和 LLM 文件。

安装
要求 Astro 7 内 7.4.13 或更新版本、Node.js 22.23.4 或更新版本、Basecoat 1 内 1.2.1 或更新版本,以及 Tailwind CSS 4 内 4.3 或更新版本。1.1 版本不再支持 Astro 6。
将 ReallySimpleDocs 添加到 Astro 站点:
npm install reallysimpledocs basecoat-css tailwindcss
配置集成:
// astro.config.mjs
import { defineConfig } from "astro/config";
import reallySimpleDocs from "reallysimpledocs/astro";
export default defineConfig({
integrations: [
reallySimpleDocs({
docsDir: "./docs",
routeBase: "/docs",
style: "nova",
site: {
title: "Acme Docs",
description: "Documentation for Acme.",
url: "https://docs.example.com",
favicon: "favicon.svg",
socialImage: "social.png",
},
}),
],
});
创建你的第一个文档页面:
docs/
├── docs.json
└── index.md
{
"menu": [
{
"type": "group",
"label": "Docs",
"items": [{ "slug": "index", "icon": "info" }]
}
]
}
# Introduction
Welcome to the docs.
它提供什么
- 由 Markdown 和 MDX 文件生成的静态文档路由。
- 来自 docs/docs.json 的侧边栏导航。
- 内置命令对话框的 Lunr 搜索。
- 带复制按钮的语法高亮代码块。
- llms.txt、llms-full.txt,以及每页 Markdown 导出。
- Basecoat 样式,搭配用于文档界面的特定样式 RSD CSS。
- 用于附加 head 内容、侧边栏外观和头部控件的组件插槽。
自定义
使用 components.ContentHeader 在搜索和内置主题切换之间添加控件:
reallySimpleDocs({
components: {
ContentHeader: "./src/components/ContentHeader.astro",
},
});
使用 components.Head 向 <head> 添加标签。RSD 内置的元数据、主题设置、Basecoat JavaScript(包括代码复制)和搜索行为仍会渲染。
使用 customCss 导入 Basecoat 和 RSD 样式之后的项目 CSS:
reallySimpleDocs({
style: "nova",
customCss: ["./src/docs.css"],
});
只有当你自己提供完整的 Tailwind/Basecoat/RSD 样式表流水线时,才使用 css: false。这种情况下 RSD 会导出自己的 CSS:
@import "reallysimpledocs/css";
文档之外的搜索
在任意需要文档搜索的 Astro 页面上渲染导出的 CommandDialog:
---
import { CommandDialog } from "reallysimpledocs/components";
---
<CommandDialog />
<button type="button" class="btn" onclick="window.rsdOpenCommandSearch?.()">
Search docs
</button>
本地开发
npm install
npm run dev
在发起 pull request 之前运行检查:
npm run check
它会构建站点,检查构建产物(scripts/assert-site-output.mjs),然后打包该包并从 tarball 构建一个一次性消费者应用(npm run smoke:consumer)。CI 在每次 pull request 和推送到 main 时运行相同的命令。使用 npm pack --dry-run 查看哪些文件会被发布。
文档
前往 reallysimpledocs.com。
支持
- 报告问题
- 在 GitHub 上给项目加星
许可证
发布
发布说明和升级要求见 CHANGELOG.md。
分阶段的 npm 发布和文档部署流程见 CONTRIBUTING.md 中的发布工作流。