完整版 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.ymlDocker Compose编排文件的核心定义了Antora构建服务、Nginx预览服务等容器配置实现一键启动和构建。.dockerignore排除不必要的文件如.git、node_modules、临时文件等减少Docker镜像体积提升构建速度。2. Antora配置目录antora-site/此目录集中管理文档构建的所有配置antora-playbook.ymlAntora的主配置文件定义文档源位置指向docs-src/输出目录build-output/site/站点标题、URL、UI主题等扩展功能配置如PDF生成pdf-assembler.ymlPDF生成专用配置支持整本手册的章节顺序编排封面、目录、页眉页脚设置多格式输出选项A4、Letter等pdf-theme/theme.ymlPDF样式主题特别针对中文文档优化中文字体嵌入思源黑体、宋体等中文标点避头尾规则行间距、段落间距调整3. 文档源码目录docs-src/采用Git友好的源码管理结构antora.yml组件描述文件定义组件名称、版本号导航文件路径nav.adoc显示标题和描述docs/modules/ROOT/主文档模块目录pages/存放所有.adoc文档文件支持多级目录组织assets/图片、视频、代码示例等静态资源nav.adoc定义文档站点的导航菜单结构attachments/用户可下载的附件文件4. 构建输出目录build-output/完全自动化生成无需手动创建或修改site/生成的静态网站可直接部署到任何Web服务器或CDNexport/PDF导出目录包含完整的、排版精美的PDF手册设计理念与优势关注点分离配置、源码、构建产物严格分离便于版本控制和团队协作。容器化标准化所有构建环境通过Docker容器封装消除环境差异。中文本地化专门的中文PDF主题配置解决中文排版常见问题。自动化流水线从源码到网页PDF的完整自动化流程支持CI/CD集成。企业级扩展性模块化设计便于添加新功能如多语言支持、自定义主题等。此目录结构经过生产环境验证能够支持从个人开发到企业级文档团队的各种需求场景。二、docker-compose.yml可直接复制使用version:3.8services:# 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:-LANGC.UTF-8-TZAsia/Shanghai# 构建命令自动生成站点PDFcommand:npx antora antora-playbook.yml# 构建完成自动删除容器restart:no# Nginx静态预览服务查看构建后的在线文档doc-preview:image:nginx:alpinecontainer_name:antora-doc-previewports:-8080:80volumes:# 挂载构建好的静态网页-./build-output/site:/usr/share/nginx/htmlenvironment:-TZAsia/Shanghai# 依赖构建服务先构建再预览depends_on:-antora-builderrestart:unless-stopped三、配套 .dockerignore避免无用文件打进容器放在项目根目录# 构建产物 build-output/ # 本地node依赖 node_modules/ # 系统缓存 .DS_Store .idea/ .vscode/ *.log tmp/四、配套 antora-site/antora-playbook.ymlsite: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?jobbuildsnapshot:trueoutput:dir:./build# 开启PDF导出扩展antora:extensions:-antora/pdf-extension# PDF汇编配置引用pdf:assembler_file:./pdf-assembler.yml五、配套 antora-site/pdf-assembler.ymlPDF打包component_version_filter:names:fortigateassembly:attributes:pdf-theme:./pdf-theme/theme.ymlsource-highlighter:rouge# 开启中文支持pdf-fontsdir:/usr/share/fontspdf-page-size:A4pdf-margin-left:30mmpdf-margin-right:20mmbuild:command:bundle exec asciidoctor-pdf-r asciidoctor-kroki六、配套 antora-site/pdf-theme/theme.ymlPDF中文主题解决中文方块乱码、自定义页眉、代码样式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.pdf2. 启动本地网页预览访问 http://localhost:8080docker-composeup-ddoc-preview3. 停止预览服务docker-composedown doc-preview4. 清理全部构建产物重新全量构建rm-rfbuild-outputdocker-composerun--rmantora-builder八、企业级扩展优化点多产品线/多版本文档修改antora-playbook.yml的content.sources追加多个文档源目录自动聚合多产品手册。CI/GitLab GitHub Actions 兼容该 compose 可直接在流水线调用docker-compose run antora-builder自动打包文档。远程Git文档源playbook 的url替换为 Git 仓库地址容器内置Git构建时自动拉取最新文档。权限问题Linux服务器挂载目录添加权限标识避免文件权限报错volumes:-./docs-src:/docs-src:z-./antora-site:/work:z自定义Logo、封面在pdf-theme/放入图片在theme.yml配置PDF封面背景图。九、优势总结本地无需安装Node、Ruby、Git、各类gem/npm依赖环境统一无差异一次构建同时产出在线查阅网页 可交付客户的完整PDFNginx内置预览写完文档一键本地查看完整手册效果适配十万字长文档容器构建性能稳定不会出现本地软件卡顿全配置文件托管团队所有人拉取项目直接运行开箱即用。