Newshot

Show HN:ReallySimpleDocs——基于 Astro 的现代化 AI 就绪文档站点

Translation(model translation, not the source's own text)

ReallySimpleDocs

一个面向 Astro 的简单文档系统,使用 Basecoat 和 Tailwind CSS 构建。

ReallySimpleDocs 让文档保持可移植:内容放在 docs/,导航放在 docs/docs.json,由 Astro 集成负责文档 UI、搜索、Markdown 导出和 LLM 文件。

ReallySimpleDocs 截图
ReallySimpleDocs 截图

安装

要求 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 中的发布工作流。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗