文档库
文档站搭建
从依赖安装到本地预览，快速启动一个通用的 Doks/Hugo 文档站。
本站使用 Node.js 管理前端依赖，并通过 Hugo 生成静态页面；日常维护优先使用 npm 脚本，避免不同 Hugo 版本混用。
官方参考
这类站点的核心思路是：用 Hugo 生成静态页面，用 Doks 提供文档主题、导航、搜索、短代码和样式体系。
适用场景
当需要整理教程、记录部署流程、修改页面样式或发布前检查时，按本文流程启动文档站。
文档站主要负责沉淀三类内容：
- 导航站的维护方法。
- 文档站自己的搭建和发布方法。
- Halo2 博客的部署、运维和排障方法。
环境准备
需要具备：
- Node.js LTS，用于运行 npm 脚本。
- npm，用于安装前端依赖。
- Git，用于提交和推送。
- 项目内置 Hugo，由
hugo-installer安装到node_modules/.bin/hugo。
检查版本：
node --version
npm --version
git --version
进入项目：
cd ~/projects/doks-site
安装依赖
首次拉取项目，或者 node_modules/ 不存在时：
npm install
如果依赖损坏，可以重新安装：
npm run clean:install
npm install
启动本地服务
Doks 官方新项目通常使用 npm run dev 启动开发服务。维护已有项目时，优先查看 package.json 里的 scripts，按项目实际脚本执行。
本项目常见默认启动：
npm run start
指定端口：
npm run start -- --port 1324
常用访问地址：
http://localhost:1324/
http://localhost:1324/docs/
端口被占用怎么办？
换一个端口即可，例如：
npm run start -- --port 1325
如果要查占用进程：
lsof -i :1324
目录结构
常改位置：
| 路径 | 用途 |
|---|---|
content/en/docs/ | 文档内容 |
content/en/blog/ | 博客类内容 |
layouts/index.html | 首页结构 |
layouts/docs/ | 文档页模板 |
layouts/partials/sidebar/ | 侧边栏和目录 |
layouts/partials/header/ | 顶部导航 |
layouts/partials/footer/ | 页脚 |
assets/scss/ | 主题样式 |
assets/js/ | 前端脚本 |
config/_default/menus/menus.en.toml | 菜单配置 |
新增文档
文档页放在 content/en/docs/ 下。每个栏目一个目录：
content/en/docs/webstack/
content/en/docs/help/
content/en/docs/halo/
新增页面需要 front matter：
---
title: "页面标题"
description: "页面描述"
lead: "页面导语"
date: 2026-06-10T16:20:00+08:00
lastmod: 2026-06-10T16:20:00+08:00
draft: false
images: []
menu:
docs:
parent: "help"
weight: 640
toc: true
---
字段说明：
| 字段 | 说明 |
|---|---|
title | 页面标题 |
description | SEO 和列表描述 |
lead | 页面标题下方导语 |
menu.docs.parent | 所属左侧栏目 |
weight | 栏目内排序 |
toc | 是否显示右侧目录 |
Markdown 规范
建议：
- 从
##开始组织正文标题。 - 命令统一使用代码块。
- 路径、文件名、变量名使用行内代码。
- 一屏内不要堆太多项目符号，必要时拆成表格。
- 真实密码、Token、Cookie、数据库文件不要写进文档。
常用提示块：
{{< alert icon="i" text="这里写提示内容。" >}}
折叠详情：
{{< details "标题" >}}
这里写展开内容。
{{< /details >}}
本地检查
每次修改后至少检查：
- 首页：
/ - 文档索引：
/docs/ - 导航站文档：
/docs/webstack/introduction/ - 文档站文档：
/docs/help/start/ - Halo2 文档：
/docs/halo/deployment/
重点看：
- 左侧导航是否展开正确。
- 右侧目录是否匹配标题。
- 代码块是否可读。
- 提示块是否不贴边。
- 深色模式是否保持可读。
- 手机宽度下导航是否正常。
构建检查
提交前执行：
npm run lint
npm run build
如果只改样式，可以先跑：
npm run lint:styles
构建输出在 public/。它只是本地构建结果，不代表线上站点已经更新。