docmd 会生成静态 HTML，因此非常适合轻量、可复现的 Docker 容器。根据您的使用场景，有两种不同的方式。

官方 Docker 镜像

借助官方镜像，您可以在本地零安装的情况下构建并提供文档服务。它支持多种架构（linux/amd64 和 linux/arm64）。

快速开始

# 拉取指定版本（推荐做法 —— 替换为所需的版本号）
docker pull ghcr.io/docmd-io/docmd:0.8.8

# 构建文档（挂载本地 docs 并将产物输出到 ./site）
docker run -v $(pwd)/docs:/docs -v $(pwd)/site:/site ghcr.io/docmd-io/docmd:0.8.8 build

# 运行内置的演示站点
docker run -p 3000:3000 ghcr.io/docmd-io/docmd:0.8.8

Docker Compose

使用 Docker Compose 在同一个工作流中完成构建与服务：

version: '3.8'
services:
  docs:
    image: ghcr.io/docmd-io/docmd:0.8.8
    command: build
    volumes:
      - ./docs:/docs
      - ./site:/site
      - ./docmd.config.json:/docmd.config.json:ro

  serve:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro
    depends_on:
      - docs

镜像详情

自定义工作目录与文件归属

镜像默认 WORKDIR /docs，但您可以将项目挂载到容器内的任意路径并从那里运行。通过 -w 覆盖工作目录，使其与项目布局一致：

# 在容器内的自定义工作目录中运行
docker run -v $(pwd):/workspace -w /workspace ghcr.io/docmd-io/docmd:0.8.8 init

入口脚本会自动检测挂载目录的 uid:gid，并在执行任何命令前通过 su-exec 切换到该身份。docmd init、docmd build 或 docmd dev 写入的文件始终归属正确的宿主机用户，无需传递 -u 参数。

自定义 Dockerfile（通过 Deployer）

对于生产环境的自托管场景，可使用 Deployer 生成一份与您项目配置匹配的 Dockerfile：

npx @docmd/core deploy --docker

它会生成一个采用多阶段构建的 Dockerfile：

1. 构建阶段 (Build stage) — 安装您精确锁定的 @docmd/core 版本并执行构建。
2. 服务阶段 (Serve stage) — 将产物复制到一个精简的 nginx:alpine 镜像中。

同时生成 Docker 与 Nginx 配置，以获得完整的自托管方案：

npx @docmd/core deploy --docker --nginx

构建与运行

docker build -t my-docs .
docker run -p 8080:80 my-docs

您的文档将在 http://localhost:8080 上线。