Authelia 文档贡献指南：从 Hugo 站点结构到 authelia-gen 文档生成器全解析

2026-09-10 18:59:29作者：庞眉杨Will

Authelia 的官方文档网站基于 Hugo 与 Doks 主题构建，其内容以 Markdown 形式存放在仓库的 docs 目录中，与网站 URL 路径一一对应。本文以 docs/content/contributing/prologue/documentation-contributions.md 为主线，系统讲解文档的编辑流程、本地预览方法、authelia-gen 文档生成器的使用，以及 Front Matter 中每个字段的作用，并辅以仓库源码证据，帮助你在修改 Authelia 源码或编写文档时，能同步维护出高质量、机器可读的项目文档。

站点架构：Hugo + Doks 下的文档组织方式

Authelia 的网站建立在 [Hugo] 之上，使用 [Doks] 主题。Hugo 是静态网站生成器，而 Doks 基于 Thulite 生态（从 docs/package.json 可以看到项目依赖了 thulite、@thulite/doks-core、@thulite/seo、@thulite/images 等包），提供文档站的侧边栏、目录（TOC）、搜索等开箱即用的能力。Hugo 的 [Shortcodes] 机制允许在 Markdown 中嵌入可复用的参数化片段，例如文档中用于渲染配置示例、告警框等的短代码，都在 docs/layouts/_shortcodes 目录中定义。

文档内容的目录结构遵循"路径即 URL"的约定：docs/content 下的文件路径直接映射为网站 URL。例如 docs/content/contributing/prologue/documentation-contributions.md 对应的就是 /contributing/prologue/documentation-contributions/。此外，从该文档的 Front Matter 可以看出，它还有一个 alias 字段（/contributing/prologue/documentation），用于保留旧 URL 的跳转，避免链接失效。

修改文档：直接编辑 Markdown 即可

贡献文档的门槛很低：任何人都可以直接编辑对应文档的 Markdown 源文件。在大多数页面底部，Authelia 都放置了指向该页面 Markdown 源文件的直接链接，方便读者快速定位到待修改的文档。修改后的内容会与网站 URL 保持同路径对应，例如想修改"集成指南"中的某个页面，就直接编辑 docs/content/integration 下对应的 .md 文件。

值得注意的编辑约定可参考 docs/content/contributing/guidelines/documentation.md：文档中的示例域名统一使用 example.com（或其子域）；示例证书有效期一律设置为从 1970-01-01 00:00:00 起 1 年；PEM 私钥块的 base64 填充 = 之前必须追加 ^invalid DO NOT USE 这类无效字符，防止读者误用示例密钥。

本地预览：三步启动开发服务器

环境要求

在本地运行 Authelia 文档网站，需要准备：

git：用于克隆仓库（若只下载仓库压缩包也可跳过）；
Node.js：版本要求见 docs/package.json 中的 engines 字段（当前为 >=24.13.0）；
pnpm：包管理器，engines 中要求 pnpm@12（当前 packageManager 锁定为 pnpm@12.3.4）。

启动步骤

在终端中依次执行：

git clone https://github.com/authelia/authelia.git
cd authelia/docs
pnpm install
pnpm dev

然后打开浏览器访问 http://localhost:1313/。pnpm dev 实际执行的是 hugo server --disableFastRender --noHTTPCache（见 docs/package.json 的 scripts 段），它会在本地启动 Hugo 开发服务器并开启实时刷新，因此修改页面后浏览器会即时呈现效果。本地开发时还会注入非严格的 CSP 策略（'self' 'unsafe-eval'），相关内容可从 cmd/authelia-gen/const.go 中看到定义。

Hugo 本体并未直接写入依赖，而是通过 optionalDependencies 中的 hugo-extended 提供，保证了环境一致性。若需要构建生产版本，可运行 pnpm build（对应 hugo --minify --gc）。

文档生成器：authelia-gen 与自动化产出

Authelia 的文档并非全部手写，大量内容由代码生成器 authelia-gen 自动产出，确保文档与源码永远同步。

生成器维护的目标文件

根据原文档与 cmd/authelia-gen/const.go 中的常量定义，生成器主要维护以下三类文件：

目标位置	生成依据	仓库常量佐证
docs/data（`configkeys.json`、`misc.json`、`languages.json` 等）	仓库内各类变更	`dirDocsData`、`fileDocsDataConfigKeys` 等
docs/content/reference/cli	cobra 命令行定义	`dirDocsCLIReference`
docs/static/schemas（JSON Schema）	internal/configuration/schema 等处的 struct tag	`dirDocsStaticJSONSchemas` 及配置/用户数据库/TOTP/WebAuthn/导出等 Schema 文件常量

以 cmd/authelia-gen/cmd_docs_cli.go 为例，docs cli 子命令会依次对 authelia（来自 internal/commands 的 commands.NewRootCmd()）、authelia-scripts（来自 cmd/authelia-scripts/cmd）和 authelia-gen 自身的 cobra 命令树调用 doc.GenMarkdownTreeCustom，为每个命令生成独立的 Markdown 参考页并写入 docs/content/reference/cli/<命令名>/，同时生成带 weight（authelia 为 900、authelia-gen 为 910、authelia-scripts 为 920）的 _index.md 用于控制侧边栏顺序。

再以 cmd/authelia-gen/cmd_docs_data.go 为例：

docs data misc 会生成 docs/data/misc.json，其中包含 CSP 指令模板（${NONCE} 占位符、生产与开发两套策略）、当前版本号 Latest，以及 PBKDF2 各哈希变体（SHA-512/384/256/224/1）的默认迭代次数与 FIPS 状态，数据直接来源于 internal/configuration/schema 中的 PBKDF2VariantDefaultIterations；
docs data keys 会反射遍历 schema.Configuration{} 的 struct tag，生成 docs/data/configkeys.json，为每个配置键标注是否为 Secret，并基于 configuration.ToEnvironmentSecretKey / ToEnvironmentKey 推导对应的环境变量名（前缀与分隔符取自 configuration.DefaultEnvPrefix、configuration.DefaultEnvDelimiter）。

日期同步：git 历史驱动的 Front Matter 维护

除内容外，生成器还会维护文档 Front Matter 中的 date 字段。源码位于 cmd/authelia-gen/cmd_docs_date.go：docs date 子命令会遍历 docs/content 下所有 .md 文件，读取其 Front Matter，然后调用 git log -1 --diff-filter=A --pretty=format:%cD -- <path> 获取该文件首次被添加进 git 历史的提交日期（commit date，RFC 2822 格式），并将其回写为 YAML 时间戳格式（2006-01-02T15:04:05-07:00）。这样，文档的 date 就始终等于"首次创建时间"，即使后续被反复修改也不会漂移。

Front Matter 字段详解

Authelia 文档的每个 Markdown 文件顶部都有一段 YAML Front Matter，控制页面的展示与 SEO 行为。典型结构如下：

---
title: "A Page Title"
description: "This is a description of the page."
summary: "This is a page lead."
date: 2022-03-19T04:53:05+00:00
draft: false
weight: 100
toc: true
---

理解 Open Graph Protocol

要理解 title、description、date 等字段的用途，需先了解 [Open Graph Protocol]（OGP）：这是由 Meta/Facebook 提出的协议，绝大多数社交媒体平台通过读取网页中特定的 HTML <meta /> 标签来生成链接预览。Authelia 文档的 SEO 渲染逻辑位于 docs/layouts/_partials 与 @thulite/seo 组件中，Front Matter 中的字段会被映射为对应的 <meta /> 标签。

各字段说明

以下是 Authelia 文档中常用 Front Matter 字段的逐一说明：

字段	类型	作用
`title`	String	配置 `<title />` 元素、页面第一个 `<h1 />` 元素，以及 OGP 的 `og:title` 值
`description`	String	配置页面的描述信息与 OGP 的 `og:description` 值，通常用于搜索引擎摘要
`summary`	String	配置页面标题（`title`）之后的第一段引导文字（页面导语）。注意：仓库内大量页面实际使用 `lead` 字段（如 docs/content/reference/cli/authelia/_index.md 等由生成器产出的文件即含 `lead`），两者均为"页面引言"类字段，编写时以页面实际使用的字段为准
`date`	Timestamp	配置 OGP 的 `og:article:published_time` 值，同时用于博客归档排序（参见 docs/content/blog）
`draft`	Boolean	控制页面可见性，为 `true` 时页面不可见
`menu`	Dictionary	配置页面在菜单中的挂载关系
`weight`	Integer	配置页面在菜单中的位置以及分页（pagination）的顺序
`toc`	Boolean	启用或禁用"Table of Contents / On This Page"（页内目录）区块
`community`	Boolean	启用或禁用 Community 页面头部，当前仅对 Integration 板块生效
`seo`	Dictionary	生成器产出的页面常带 `seo` 块，内含 `title`、`description`、`canonical`、`noindex` 等可选自定义项，用于覆盖默认 SEO 元数据（如 cmd/authelia-gen/cmd_docs_cli.go 生成的模板）
`alias`	字符串/列表	为旧 URL 提供跳转别名，本文所在页面即用其保留 `/contributing/prologue/documentation` 这一历史路径
`images`	List	声明页面相关的图片资源（默认空列表），供 OGP 预览使用

实战建议

新页面务必填写 title 与 description，这直接影响搜索引擎与社交平台预览质量；
若页面按时间线或菜单顺序展示，合理设置 weight 与 date；
发布前确认 draft: false，否则页面不会出现在站点中；
修改源码后运行 authelia-gen，让生成的 CLI 参考、JSON Schema、docs/data 数据与 Front Matter 日期保持与源码一致，避免文档漂移。

小结

Authelia 的文档贡献流程可以归纳为三条主线：直接编辑（Markdown 与 URL 同路径、页面底部提供源文件链接）、本地验证（pnpm install && pnpm dev 实时预览）、生成器维护（authelia-gen 负责 CLI 参考、JSON Schema、docs/data 与 Front Matter 日期的自动化同步）。掌握 Front Matter 中 title、description、summary/lead、date、draft、weight、toc 等字段的含义，就能写出既对读者友好、又对搜索引擎与 AI 检索友好的高质量文档。