快速开始

安装依赖、启动开发服务并发布你的第一篇文档。

项目结构

public/                     站点标志、共享样式与主题脚本
src/
├── components/             工具栏、搜索对话框与文档表格
├── content/docs/           MDX 文档及导航配置 _meta.ts
├── layouts/                全站布局与文档布局
├── lib/                    文档导航与单元测试
├── pages/                  首页、文档路由和 404
└── staticrypt-template.html 密码页模板
scripts/                    构建期加密与产物检查

本地开发

使用仓库 .node-version 指定的 Node.js 版本,在根目录运行:

npm ci
npm run dev

Astro 会在 http://localhost:4321 启动开发服务。修改 MDX 后,可在浏览器中查看更新。

检查代码

npm run typecheck
npm test

构建并预览

在本地 .env 中设置 STATICRYPT_PASSWORD,然后运行:

npm run build
npm run preview

生产文件写入 dist/。构建先生成静态页面,再加密受保护文档,随后建立搜索索引并检查产物。请使用构建预览验证搜索和解密。

主题切换

站点默认使用亮色主题。点击工具栏右侧的主题按钮可切换亮色与暗色,手动选择会保存在当前浏览器。共享样式位于 public/sage.css。

搜索

点击工具栏中的搜索按钮,或使用 Ctrl+K(macOS 上为 ⌘K)打开搜索。使用 Tab 在输入框、关闭按钮和结果之间移动,按 Esc 关闭搜索并返回原焦点。

Pagefind 按需加载构建生成的索引。索引收录标记为 data-pagefind-body 的正文,导航、页面目录和受保护正文均排除在外。

添加新文档

  1. 在 src/content/docs/ 创建 .mdx 文件,写入 title 和可选的 description。
  2. 在 src/content/docs/_meta.ts 中添加标题与路径:
{ label: '教程', slug: 'tutorial' }

路径相对于 src/content/docs/,省略扩展名。使用 items 可将多个页面放入可折叠的分组。首页文档列表和侧边栏均读取该配置。

部署

静态托管平台的构建命令为 npm run build,发布目录为 dist。在构建环境中配置 STATICRYPT_PASSWORD。仓库中的 docs/cloudflare-pages-migration.md 说明了如何从 Vercel 迁移到 Cloudflare Pages。

Markdown 语法参考

元素 语法
标题 # H1 ## H2 ### H3
粗体 **粗体**
斜体 *斜体*
链接 [文字](url)
图片 ![说明](url)
行内代码 使用一对反引号
代码块 使用三个反引号围住代码,可在第一行标注语言
表格 使用竖线分隔列