OpenCart 文档站构建实战：基于 Daux.io 的 Markdown 文档生成与部署指南

• 电商
• 后端

本篇技术指南围绕 OpenCart 仓库中内置的文档生成工具Daux.io（位于 tools/daux.io）展开，讲解如何以"文件夹 + Markdown 文件"的组织方式自动生成结构化的在线文档站。读完本文，你将掌握 Daux.io 的安装方式、generate与serve两大 CLI 命令、文档目录与排序规范、global.json配置体系、静态站点生成与 Apache/Nginx/IIS 部署，并理解 OpenCart 官方文档目录（docs）如何由该工具驱动产出。

什么是 Daux.io：为开发者设计的 Markdown 文档生成器

Daux.io是一个基于 PHP 的文档生成器，它使用简单的文件夹结构和 Markdown 文件即时生成自定义文档。其核心设计理念是"开发者友好"：不需要数据库、不需要构建步骤，把 Markdown 放进docs目录即可得到一套带导航、搜索和主题的文档网站。

从仓库中的 composer.json 可以确认其技术栈：核心依赖包括league/commonmark（CommonMark 规范解析）、league/plates（PHP 模板引擎）、scrivo/highlight.php（语法高亮）、symfony/console（CLI 框架）以及symfony/yaml（配置解析），PHP 要求>=8.1。项目 PSR-4 自动加载命名空间为Todaymade\Daux\（映射到libs/目录）。

在 OpenCart 仓库中，Daux.io 正是官方文档（docs）的生成引擎：docs目录下按getting-started、admin-interface、developer-guide等子目录组织大量 Markdown 文档，并由 docs/SUMMARY.md 定义目录结构。此外，tools/generate_api.php 展示了更上层的一种用法——通过脚本驱动其他工具（ApiGen）生成 API 文档，体现了仓库对"文档生成工具链"的整体依赖。

核心特性一览

Daux.io 的功能特性可归纳为以下要点：

• 100% 移动端响应式：默认基于 Bootstrap 构建，自适应各种屏幕尺寸；
• CommonMark 兼容：遵循 CommonMark 规范解析 Markdown；
• 支持 Markdown 表格：文档中可直接书写表格语法；
• 自动生成首页/落地页（landing page）：在docs根目录放置index.md即可；
• 自动语法高亮：内置代码高亮能力；
• 自动生成导航：由文件夹结构直接推导嵌套导航；
• 4 套内置主题：daux-blue、daux-green、daux-navy、daux-red，也支持自定义主题；
• 扁平化设计风格：现代、清爽的界面；
• 可分享、利于 SEO 的 URL：生成的链接可分享、对搜索引擎友好；
• 基于 Bootstrap：前端框架底座；
• 无构建步骤：文档即改即生效；
• Git/SVN 友好：纯静态文件结构，方便版本管理；
• 支持 Google Analytics 与 Piwik Analytics：可在配置中开启统计；
• 静态输出生成：可一次性生成整套静态 HTML。

在 OpenCart 仓库的 global.json 中可以看到这些特性的实际配置痕迹："theme": "daux-blue"（主题）、"search": true（站内搜索）、"breadcrumbs": true（面包屑）、"auto_landing": true（自动落地页）、"clean_urls": true（干净 URL）、"google_analytics": false与"piwik_analytics": false（统计开关）等。

安装 Daux.io

通过 PHP + Composer 安装

前提是机器已安装 PHP（8.1.0 及以上）与 Composer，然后全局安装：

composer global require daux/daux.io # 在你的 `docs` 文件夹旁边运行 daux generate

之后即可使用daux命令行生成文档。若提示命令找不到，请确认$PATH中包含~/.composer/vendor/bin。

从 composer.json 可以看到其bin字段声明了bin/daux可执行入口，require中锁定了php: ">=8.1"及上文提到的各依赖组件，这解释了为什么全局安装后能直接获得daux命令。

通过 Docker 使用

若希望避免污染本地 PHP 环境，可以使用官方 Docker 镜像：

docker run --rm -it -w /build -v "$PWD":/build -u "$(id -u):$(id -g)" daux/daux.io daux

该命令将当前目录挂载为容器内的/build工作目录，并以当前用户身份（-u "$(id -u):$(id -g)"）运行，避免生成的文件出现权限归属问题。--rm表示容器退出后自动清理，-it提供交互式终端。仓库 tools/daux.io/Dockerfile 即该镜像的构建定义。

daux命令行：generate 与 serve

daux命令共提供两个子命令：generate与serve。不带任何参数直接运行daux时，会自动执行generate。运行daux --help可查看每个命令的详细参数说明。

从源码 tools/daux.io/libs/Console/Generate.php 可以看到generate命令的实际定义：

其执行流程（execute方法）依次为：解析参数 →prepareConfig构建配置 → 实例化Daux（静态模式Daux::STATIC_MODE）→ 加载处理器 →generateTree()构建文档树 →getGenerator()->generateAll()输出全部页面。

serve命令（tools/daux.io/libs/Console/Serve.php）则支持两个选项：

该命令以实时模式（Daux::LIVE_MODE）构建配置，并强制使用 HTML 格式（$builder->withFormat('html')，注释明确写着 "Daux can only serve HTML"）；随后将配置序列化写入临时文件，通过环境变量（DAUX_CONFIG、DAUX_VERBOSITY、DAUX_EXTENSION）传递给由 index.php 启动的 PHP 内嵌服务器。index.php在cli-server模式下模拟 Apache 的mod_rewrite：对已存在的文件直接返回，其余请求统一交给/index.php，最终由Todaymade\Daux\Server\Server::serve()处理——这也是clean_urls得以生效的底层机制。

文档目录组织规范

文件夹与导航

默认情况下，生成器只扫描docs文件夹，将内部所有子文件夹递归转换为嵌套导航。也就是说：

• 你可以在docs内任意层级嵌套文件夹，得到你想要的精确结构；
• 文件夹结构会原样映射为多层级的左侧导航菜单；
• 如果想将文档放在docs之外（例如 Daux.io 根目录外部），可以在global.json中用docs_directory指定文档路径。

OpenCart 的 docs 目录正是这一模式的直接实践：顶层按主题划分为getting-started、admin-interface、api、database、design、developer-guide等文件夹，admin-interface下再细分为cms、customers、marketing、overview、reports、sales、system等子目录，每个子目录内是一组 Markdown 文件。仓库根目录的 docs/SUMMARY.md 则是对应导航顺序的补充约定。

文件命名规则

生成器会扫描docs文件夹及其子文件夹内的 Markdown 文件（扩展名*.md与*.markdown）。文件名必须使用下划线代替空格，示例如下：

正确示例：

• 01_Getting_Started.md→ 显示为 "Getting Started"
• API_Calls.md→ 显示为 "API Calls"
• 200_Something_Else-Cool.md→ 显示为 "Something Else-Cool"
• _5_Ways_to_Be_Happy.md→ 显示为 "5 Ways To Be Happy"

错误示例：

• File Name With Space.md→ 生成失败（文件名含空格）

排序规则

默认情况下文件与文件夹按字母数字顺序排序；若要自定义顺序，可以用"数字 + 下划线"作为前缀，例如/docs/01_Hello_World.md与/docs/05_Features.md，这样Hello World会排在Features之前。前缀数字会被从导航和 URL 中剔除。对于"6 Ways to Get Rich"这类以数字开头的文件名，使用/docs/_6_Ways_to_Get_Rich.md（下划线 + 数字）即可规避冲突。

从源码 tools/daux.io/libs/Tree/Builder.php 可以推断，排序与命名清洗逻辑由文档树构建器统一处理：遍历目录、按规则排序条目、并将下划线转换为空格作为显示标题、剔除排序前缀生成 URL 片段。

落地页（Landing Page）配置

项目首页

如果想为项目创建漂亮的落地页，只需在docs根目录创建一个index.md文件，它将被用作首页。还可以通过配置文件为首页添加副标题（tagline）和图片：

{ "title": "Daux.io", "tagline": "The Easiest Way To Document Your Project", "image": "app.png" }

说明：image可以是本地或远程图片；使用<base_url>约定可引用 Daux 实例的根目录。

在 OpenCart 的 docs/README.md 中可以看到落地页的实际写法：文件顶部用 YAML front matter（icon: hand-wave）声明图标，正文以# Introduction开头介绍 OpenCart 与文档指南定位，并用 HTML 卡片（<table>{ "title": "Daux.io" }

主题（Themes）

内置 4 套基于 Bootstrap 的主题，通过theme选项选择：

• daux-blue
• daux-green
• daux-navy
• daux-red

{ "html": { "theme": "daux-green" } }

主题的 SCSS 源码位于 tools/daux.io/src/css/theme_daux：theme-blue.scss、theme-green.scss、theme-navy.scss、theme-red.scss分别对应四套配色，公共样式集中在theme.scss与_variables.scss等 partial 文件中，支持通过修改变量自定义品牌色。

更多选项

Daux.io 还提供大量其他配置项，按类别划分包括：

• 全局选项（Global options）：title、tagline、author、image、languages（多语言）、cache、format、processor、ignore（忽略文件/文件夹）、language、strings（界面文案，内置 en/fr/de/it 等语言的键值表）、timezone等；
• HTML 选项（HTML export）：html.theme、html.breadcrumbs、html.breadcrumb_separator、html.toggle_code、html.date_modified、html.auto_landing、html.search、html.auto_toc、html.inherit_index、html.jump_buttons、html.repo、html.links、html.buttons、html.google_analytics、html.piwik_analytics等；
• Confluence 选项（Confluence upload）：confluence.prefix、confluence.delete等。

在 OpenCart 的 tools/daux.io/global.json 中可以找到上述全部选项的带默认值示例，例如"languages": {}、"ignore": {"files": [], "folders": []}、"format": "html"、"timezone": "America/Los_Angeles"、"live": {"clean_urls": true}，以及html区块中"breadcrumb_separator": "Chevrons"、"auto_toc": false、"jump_buttons": true等细化项。此外该配置还包含一个完整的strings多语言文案表（en/fr/de/it），展示了如何为界面元素（如搜索占位符、上一页/下一页、目录等）提供本地化文本。

运行文档站

远程部署（PHP 环境）

将仓库中的文件拷贝到可运行PHP 8.1.0 或更新版本的 Web 服务器即可直接运行。部署后，只需把 Markdown 文档放入docs文件夹，由 Apache 或 Nginx 指向站点根目录即可。

本地预览（推荐）

本地有几种方式运行文档。推荐使用daux serve，它会启动 PHP 内嵌服务器（PHP built-in server）：

默认服务地址为 http://localhost:8085。

该模式主要面向正在大量编写/更新文档、需要即时预览改动的场景——Daux.io 的"无构建步骤"特性在这里体现得最充分：编辑 Markdown 保存后刷新浏览器即可看到变化。

daux serve还支持自定义主机与端口，例如：

daux serve --host=0.0.0.0 --port=9000

（对应源码 Serve.php 中的--host、--port选项。）

生成静态文件集

生成一套带完整导航的静态页面，可上传到静态站点托管服务（如 GitHub Pages 类服务）：

daux --source=docs --destination=static

该命令等同于daux generate（不带参数时默认执行 generate），将全部 Markdown 渲染为 HTML 输出到static目录，之后即可整体上传部署。OpenCart 文档站（docs/api 下的Opencart.*.html等数百个页面）即属于这类由工具链生成的静态输出形态。

在 IIS 上运行

如果在本地或远程配置了 IIS 网站，通常需要一个web.config，包含两部分内容：

1. 重写规则（rewrite）：用于处理干净 URL（clean urls）；
2. MIME 类型处理器（mime type handler）：若使用自定义主题，需要为.less文件配置 MIME 类型。

Clean URLs 重写规则

web.config需要在<system.webServer>下添加<rewrite>条目：

<configuration> <system.webServer> <rewrite> <rules> <rule name="Main Rule" stopProcessing="true"> <match url=".*" /> <conditions logicalGrouping="MatchAll"> <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" /> <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" /> </conditions> <action type="Rewrite" url="index.php" appendQueryString="false" /> </rule> </rules> </rewrite> </system.webServer> </configuration>

该规则的含义：当请求的路径**既不是磁盘上的实际文件（IsFile取反）也不是实际目录（IsDirectory取反）**时，将请求重写到index.php（stopProcessing="true"表示命中后不再匹配后续规则）。这与 index.php 中针对 PHP 内嵌服务器的 mod_rewrite 模拟逻辑异曲同工——都是把所有"非静态资源"的请求收口到前端控制器。

注意：IIS 6 不支持上述原生重写语法，需要借助第三方 URL 重写模块（如 URL Rewriter）。

PHP 环境要求

版本要求

Daux.io 兼容 PHP 官方支持的版本，即8.1.0 及以上。这一点在 composer.json 中以"php": ">=8.1"显式声明，README 中"Running Remotely"一节也再次强调需要 PHP 8.1.0+。

必需扩展

Daux.io 需要以下 PHP 扩展才能正常工作：

• php-mbstring：多字节字符串处理（Markdown 文本解析依赖）；
• php-xml：XML 解析（Markdown 渲染管线与配置文件解析依赖）。

另外，如果页面名称中使用了非英文字符，建议额外安装php-intl扩展（国际化支持，可用于翻译"修改时间"等本地化文案——这在 composer.json 的suggest字段中有明确说明）。

在 OpenCart 的 Docker 化部署中也能找到对应印证：仓库根目录的 docker-compose.yml 与 docker/php/Dockerfile 定义了 PHP 运行环境，tools/daux.io/docker/下另有 Daux.io 自身的容器构建文件，说明文档生成工具与运行环境在容器化方案中是完整配套的。

小结：在 OpenCart 中落地 Daux.io 文档工作流

Daux.io 用"文件夹结构 + Markdown 文件 + JSON 配置"三要素取代了传统文档系统的数据库与后台管理，其价值在 OpenCart 这种大型开源项目上体现得尤为明显：

1. 内容即文件：全部文档以 Markdown 形式版本化管理在 docs 目录，Git 提交即文档更新；
2. 结构即导航：目录层级直接映射为导航菜单，新增章节只需新建文件夹与 Markdown 文件；
3. 配置驱动外观：通过 global.json /config.json一套配置即可切换主题、开启搜索、配置统计与多语言；
4. 双模式输出：开发期用daux serve即时预览，发布期用daux generate输出静态站点，适配 Apache/Nginx/IIS 及各类静态托管；
5. 生态可扩展：支持confluence输出格式（上传到 Confluence 空间）、自定义 processor 处理器与自定义主题 SCSS，为文档系统演进留足空间。

对 OpenCart 开发者而言，无论是撰写 docs/admin-interface 这类运营手册、docs/developer-guide 这类开发者文档，还是维护 API 参考（docs/api），这套工具链都提供了从写作到发布的全流程支撑。

• 电商
• 后端