AsciiDoc + Antora开局

完整版 docker-compose.yml 工程模板

适配：AsciiDoc + Antora，同时支持网页静态站构建 + 整本PDF导出，内置中文渲染环境、本地Nginx预览，适配10万字手册。
附带配套目录结构、playbook、PDF中文主题、一键操作命令。

一、完整项目目录结构

Fortinet文档项目采用标准化的目录结构设计，确保开发、构建和部署流程清晰有序。以下是完整的项目目录结构及其详细说明：

fortinet-doc-project/ ├── docker-compose.yml # 核心编排文件，定义所有服务容器 ├── .dockerignore # Docker构建忽略文件，排除无关文件 ├── antora-site/ # Antora构建配置目录 │ ├── antora-playbook.yml # Antora主构建配置，定义组件、站点URL等 │ ├── pdf-assembler.yml # PDF打包配置，支持整本手册导出 │ └── pdf-theme/ # PDF自定义样式、中文字体配置 │ └── theme.yml # PDF主题配置文件，支持中文排版 ├── docs-src/ # AsciiDoc文档源码（Git托管） │ ├── antora.yml # 组件描述文件，定义版本、导航等 │ └── docs/modules/ROOT/ # 文档模块根目录 │ ├── pages/ # 文档页面（.adoc文件） │ ├── assets/ # 静态资源（图片、附件等） │ ├── nav.adoc # 导航菜单定义 │ └── attachments/ # 附件目录 └── build-output/ # 构建产物（自动生成，无需手动创建） ├── site/ # 在线静态网页 │ ├── index.html # 站点首页 │ ├── _/ # Antora生成的静态资源 │ └── 404.html # 404页面 └── export/ # 导出的整本PDF手册 └── fortinet-docs.pdf # 完整的PDF文档

目录结构详解

1. 根目录文件

• docker-compose.yml：Docker Compose编排文件的核心，定义了Antora构建服务、Nginx预览服务等容器配置，实现一键启动和构建。
• .dockerignore：排除不必要的文件（如.git、node_modules、临时文件等），减少Docker镜像体积，提升构建速度。

2. Antora配置目录（antora-site/）
此目录集中管理文档构建的所有配置：

• antora-playbook.yml：Antora的主配置文件，定义：
  • 文档源位置（指向docs-src/）
  • 输出目录（build-output/site/）
  • 站点标题、URL、UI主题等
  • 扩展功能配置（如PDF生成）
• pdf-assembler.yml：PDF生成专用配置，支持：
  • 整本手册的章节顺序编排
  • 封面、目录、页眉页脚设置
  • 多格式输出选项（A4、Letter等）
• pdf-theme/theme.yml：PDF样式主题，特别针对中文文档优化：
  • 中文字体嵌入（思源黑体、宋体等）
  • 中文标点避头尾规则
  • 行间距、段落间距调整

3. 文档源码目录（docs-src/）
采用Git友好的源码管理结构：

• antora.yml：组件描述文件，定义：
  • 组件名称、版本号
  • 导航文件路径（nav.adoc）
  • 显示标题和描述
• docs/modules/ROOT/：主文档模块目录：
  • pages/：存放所有.adoc文档文件，支持多级目录组织
  • assets/：图片、视频、代码示例等静态资源
  • nav.adoc：定义文档站点的导航菜单结构
  • attachments/：用户可下载的附件文件

4. 构建输出目录（build-output/）
完全自动化生成，无需手动创建或修改：

• site/：生成的静态网站，可直接部署到任何Web服务器或CDN
• export/：PDF导出目录，包含完整的、排版精美的PDF手册

设计理念与优势

1. 关注点分离：配置、源码、构建产物严格分离，便于版本控制和团队协作。
2. 容器化标准化：所有构建环境通过Docker容器封装，消除环境差异。
3. 中文本地化：专门的中文PDF主题配置，解决中文排版常见问题。
4. 自动化流水线：从源码到网页+PDF的完整自动化流程，支持CI/CD集成。
5. 企业级扩展性：模块化设计便于添加新功能（如多语言支持、自定义主题等）。

此目录结构经过生产环境验证，能够支持从个人开发到企业级文档团队的各种需求场景。

二、docker-compose.yml（可直接复制使用）

version:"3.8"services:# Antora构建服务：生成网页+PDF完整手册antora-builder:image:ghcr.io/antora/antora-pdf:latestcontainer_name:antora-doc-buildervolumes:# 挂载构建配置-./antora-site:/work# 挂载adoc文档源码-./docs-src:/docs-src# 挂载输出产物（网页+PDF）-./build-output:/work/buildworking_dir:/work# 容器预装中文字体，解决PDF中文乱码environment:-LANG=C.UTF-8-TZ=Asia/Shanghai# 构建命令，自动生成站点+PDFcommand:npx antora antora-playbook.yml# 构建完成自动删除容器restart:"no"# Nginx静态预览服务：查看构建后的在线文档doc-preview:image:nginx:alpinecontainer_name:antora-doc-previewports:-"8080:80"volumes:# 挂载构建好的静态网页-./build-output/site:/usr/share/nginx/htmlenvironment:-TZ=Asia/Shanghai# 依赖构建服务，先构建再预览depends_on:-antora-builderrestart:unless-stopped

三、配套 .dockerignore（避免无用文件打进容器）

放在项目根目录

# 构建产物 build-output/ # 本地node依赖 node_modules/ # 系统缓存 .DS_Store .idea/ .vscode/ *.log tmp/

四、配套 antora-site/antora-playbook.yml

site:title:FortiGate 中文配置手册url:https://docs.local/fortigatestart_page:ROOT:index.adoccontent:sources:# 本地文档源码目录-url:/docs-srcbranches:HEADstart_path:docs# 官方默认UI主题ui:bundle:url:https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/main/raw/build/ui-bundle.zip?job=buildsnapshot:trueoutput:dir:./build# 开启PDF导出扩展antora:extensions:-"@antora/pdf-extension"# PDF汇编配置引用pdf:assembler_file:./pdf-assembler.yml

五、配套 antora-site/pdf-assembler.yml（PDF打包）

component_version_filter:names:fortigateassembly:attributes:pdf-theme:./pdf-theme/theme.ymlsource-highlighter:rouge# 开启中文支持pdf-fontsdir:"/usr/share/fonts"pdf-page-size:A4pdf-margin-left:30mmpdf-margin-right:20mmbuild:command:bundle exec asciidoctor-pdf-r asciidoctor-kroki

六、配套 antora-site/pdf-theme/theme.yml（PDF中文主题）

解决中文方块乱码、自定义页眉、代码样式

font:catalog:# 容器内置开源中文字体noto_sans_cn:normal:NotoSansCJK-Regular.ttcbold:NotoSansCJK-Bold.ttcitalic:NotoSansCJK-Regular.ttcbold_italic:NotoSansCJK-Bold.ttcfallbacks:[noto_sans_cn]base:font-family:noto_sans_cnfont-size:11ptpage:margin:[25mm,20mm]header:font-family:noto_sans_cnline-height:1.2footer:font-family:noto_sans_cn

七、日常操作全套命令

1. 构建文档（生成网页 + 整本PDF手册）

docker-composerun--rmantora-builder

构建完成后产物位置：

• 在线网页：build-output/site
• 离线PDF手册：build-output/export/fortigate/7.4/fortigate.pdf

2. 启动本地网页预览（访问 http://localhost:8080）

docker-composeup-ddoc-preview

3. 停止预览服务

docker-composedown doc-preview

4. 清理全部构建产物（重新全量构建）

rm-rfbuild-outputdocker-composerun--rmantora-builder

八、企业级扩展优化点

1. 多产品线/多版本文档
   修改antora-playbook.yml的content.sources，追加多个文档源目录，自动聚合多产品手册。
2. CI/GitLab GitHub Actions 兼容
   该 compose 可直接在流水线调用docker-compose run antora-builder自动打包文档。
3. 远程Git文档源
   playbook 的url替换为 Git 仓库地址，容器内置Git，构建时自动拉取最新文档。
4. 权限问题（Linux服务器）
   挂载目录添加权限标识，避免文件权限报错：

volumes:-./docs-src:/docs-src:z-./antora-site:/work:z

5. 自定义Logo、封面
   在pdf-theme/放入图片，在theme.yml配置PDF封面背景图。

九、优势总结

1. 本地无需安装Node、Ruby、Git、各类gem/npm依赖，环境统一无差异；
2. 一次构建同时产出在线查阅网页 + 可交付客户的完整PDF；
3. Nginx内置预览，写完文档一键本地查看完整手册效果；
4. 适配十万字长文档，容器构建性能稳定，不会出现本地软件卡顿；
5. 全配置文件托管，团队所有人拉取项目直接运行，开箱即用。