快速开始

欢迎使用 Sage,本指南将帮助你快速上手。

欢迎使用 Sage。

项目结构

src/
├── components/
│   ├── SearchDialog.astro   ← 搜索对话框(Pagefind 懒加载)
│   └── ThemeInit.astro      ← 主题初始化 + [data-theme-toggle] 绑定
├── content/docs/            ← 文档内容(丢 .mdx 即可)
│   ├── _meta.ts             ← 侧边栏配置(仅顶层这一个)
│   ├── getting-started.mdx
│   └── dev/
│       ├── architecture.mdx
│       ├── api-reference.mdx
│       └── secret.mdx       ← 加密文档
├── layouts/
│   ├── BaseLayout.astro     ← 全站外壳(head / 主题 / 搜索 / 浮动按钮)
│   └── DocsLayout.astro     ← 文档页布局(复用 BaseLayout)
├── lib/
│   └── sidebar.ts           ← 侧边栏渲染(已测试)
├── pages/
│   ├── index.astro          ← 首页
│   ├── 404.astro            ← 404
│   └── docs/
│       └── [...slug].astro  ← 文档路由
├── styles/
│   └── tokens.css           ← 设计 Token(亮色/暗色,全局共享)
└── staticrypt-template.html ← 加密页模板
scripts/
└── encrypt.mjs              ← 构建期加密步骤

本地开发

安装依赖

npm install

启动开发服务器

npm run dev

Astro 会在 http://localhost:4321 启动热重载开发服务器。

运行测试

npm test

类型检查

npm run typecheck

构建生产版本

# 加密密码从环境变量读取,仓库里不保存明文
echo "STATICRYPT_PASSWORD='your-long-password'" > .env
npm run build

构建产物输出到 dist/ 目录,为纯静态文件。构建流程:Astro 编译 → StatiCrypt 加密 → Pagefind 搜索索引。

顺序不能颠倒:先加密再建索引,否则 Pagefind 会把待加密页面的明文写进搜索索引分片。


主题切换

点击右下角浮动按钮或导航栏右侧的太阳/月亮图标切换亮色/暗色模式。

特性:

新增按钮只需加 data-theme-toggle 属性,并在按钮内放 .theme-icon-sun 与 .theme-icon-moon 两个图标。


搜索

按下 Ctrl+K(Mac: Cmd+K)呼出搜索对话框,或点击导航栏中的搜索按钮。

搜索基于 Pagefind,索引由 npm run build 生成,浏览器端按需加载 /pagefind/pagefind.js。

因为索引只在构建产物里,npm run dev 下搜索会提示”搜索索引不可用”,属预期行为。

索引只收录带 data-pagefind-body 的页面(当前是 <main>),所以导航栏、侧边栏、目录不会污染搜索结果;加密页没有该标记,也不会被索引。


添加新文档

  1. 在 src/content/docs/ 目录创建 .mdx 文件(可以放子目录)
  2. 在 src/content/docs/_meta.ts 中添加一行标题和路径
  3. 完成,构建后自动生效
# 1. 创建文件: src/content/docs/tutorial.mdx
---
title: 教程
---

## 第一步
...

# 2. 在 src/content/docs/_meta.ts 加一行:
{ label: '教程', slug: 'tutorial' }

_meta.ts 配置格式

// 单页
{ label: '快速开始', slug: 'getting-started' }

// 分组(可折叠)
{
  label: '开发指南',
  slug: 'dev',              // 可选,用作 DOM id
  items: [
    { label: '架构设计', slug: 'dev/architecture' },
    { label: '接口说明', slug: 'dev/api-reference' },
  ],
}

侧边栏只有一个顶层 _meta.ts:子目录不会各自生成导航。路由与 _meta.ts 相互独立——没有登记到侧边栏的 .mdx 依然可以访问,只是不出现在导航里。


部署


Markdown 语法参考

元素语法
标题# H1 ## H2 ### H3
粗体**粗体**
斜体*斜体*
链接[文字](url)
图片![alt](url)
代码块 \“语言 `
表格| 列1 | 列2 |