快速开始
安装依赖、启动开发服务并发布你的第一篇文档。
项目结构
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 的正文,导航、页面目录和受保护正文均排除在外。
添加新文档
- 在
src/content/docs/创建.mdx文件,写入title和可选的description。 - 在
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) |
| 图片 |  |
| 行内代码 | 使用一对反引号 |
| 代码块 | 使用三个反引号围住代码,可在第一行标注语言 |
| 表格 | 使用竖线分隔列 |