在线文档服务

English | 简体中文

这是一个轻量级 Markdown 在线文档服务。启动后会自动扫描当前目录及子目录中的 Markdown 文档，并在浏览器中渲染文档、目录树、正文大纲、搜索结果和 Mermaid 图表。

在线 Demo：https://web-docs.suqishuo.cn/

功能

• 自动发现当前目录及子目录下的 .md、.markdown 文件。
• 在线渲染 Markdown 内容。
• 支持 Mermaid 代码块渲染。
• 支持文档树浏览、全文搜索、正文大纲和相对图片路径。
• 后台定时执行 git pull --ff-only，保持 Git 仓库文件最新。
• 支持 Linux、Windows 和 Docker Compose 启动。
• 支持导出静态站点并部署到 GitHub Pages 或 Cloudflare Workers。

本地启动

首次运行可先创建虚拟环境并安装依赖。当前服务端只使用 Python 标准库，requirements.txt 保留为统一依赖入口，后续新增依赖时直接维护该文件。

Linux 或 macOS:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Linux 或 macOS:

./start-docs.sh

Windows PowerShell:

.\start-docs.ps1

Windows CMD:

start-docs.cmd

默认访问地址:

http://127.0.0.1:8090/

常用参数:

./start-docs.sh --port 8091 --no-open
./start-docs.sh --git-pull-interval 600
./start-docs.sh --no-git-pull

Docker Compose 启动

Docker 镜像会在构建时安装 requirements.txt 中的 Python 依赖。

WEB_DOCS_UID=$(id -u) WEB_DOCS_GID=$(id -g) docker compose up --build

Compose 会把 WEB_DOCS_UID 和 WEB_DOCS_GID 传给容器入口脚本。入口脚本会在容器内创建匹配的用户和用户组记录，然后用该 UID/GID 运行文档服务，避免 Git SSH 在数字 UID 没有系统用户记录时失败。

默认访问地址:

http://127.0.0.1:8090/

如需修改宿主机端口:

WEB_DOCS_PUBLISHED_PORT=8091 WEB_DOCS_UID=$(id -u) WEB_DOCS_GID=$(id -g) docker compose up --build

如果 Git remote 使用 SSH 地址，例如 git@github.com:owner/repo.git，容器内需要能读取 SSH key 和 known_hosts。Linux/macOS 可挂载宿主机 SSH 配置:

services:
  web-docs:
    volumes:
      - ./:/docs
      - ~/.ssh:/tmp/.ssh:ro

如果不挂载 SSH 配置，容器内即使已安装 ssh，git pull 也可能因为缺少私钥、缺少 known_hosts 或仓库访问权限而失败。此时日志通常会显示 Permission denied (publickey)、Host key verification failed 或 Could not read from remote repository。

更新 Dockerfile 后需要重新构建镜像:

WEB_DOCS_UID=$(id -u) WEB_DOCS_GID=$(id -g) docker compose up --build

Git 自动更新

服务默认启用后台 Git 自动拉取，每 300 秒执行一次:

git pull --ff-only

这只允许快进更新，不会自动 merge，也不会覆盖本地冲突变更。若工作区存在未提交修改、分支无法快进、认证失败或网络不可用，服务会记录错误并在下一轮继续重试。

可用环境变量:

变量	默认值	说明
WEB_DOCS_GIT_PULL	1	设置为 0、false、no 或 off 可关闭自动拉取
WEB_DOCS_GIT_PULL_INTERVAL	300	自动拉取间隔，单位秒
WEB_DOCS_GIT_PULL_TIMEOUT	120	单次拉取超时时间，单位秒
WEB_DOCS_GIT_PULL_REMOTE	空	可选 Git remote，不设置则使用当前分支 upstream
WEB_DOCS_GIT_PULL_BRANCH	空	可选 Git branch，设置 branch 但不设置 remote 时默认使用 origin

示例:

WEB_DOCS_GIT_PULL_INTERVAL=60 ./start-docs.sh --no-open

指定远端和分支:

./start-docs.sh --git-pull-remote origin --git-pull-branch main

静态站点导出

GitHub Pages 和 Cloudflare Workers 静态资源托管不会运行 Python 服务。项目提供静态导出模式，将文档清单、Markdown 正文和全文搜索数据写入生成的页面：

npm install
python3 serve-docs.py --export-static dist

生成结果位于 dist/，可以用任意静态文件服务器预览：

python3 -m http.server 8091 --directory dist

静态版本保留文档树、全文搜索、Markdown 渲染、代码高亮、Mermaid、大纲、主题切换和相对图片支持。导出时会复制 Markdown 文件、常用图片、字体、音视频、PDF 资源，以及通过 npm 安装的前端渲染库。部署后的页面从站点自身加载 marked、highlight.js 和 mermaid，不依赖外部 CDN。

dist/ 每次导出都会被重新生成，不应手工编辑其中的文件。

GitHub Pages 部署

仓库包含 .github/workflows/pages.yml。推送到 main 分支时，工作流会导出静态站点并发布到 GitHub Pages。

首次使用时，在 GitHub 仓库中进入 Settings → Pages，将 Source 设置为 GitHub Actions。之后可以推送到 main，也可以在 Actions 页面手动运行 Deploy GitHub Pages。

该配置兼容项目站点路径（例如 https://owner.github.io/repository/），无需设置固定的仓库名前缀。

Cloudflare Workers 部署

仓库包含 wrangler.toml 和 .github/workflows/cloudflare-workers.yml，使用 Workers Static Assets 发布 dist/。

当前 Demo 部署地址：https://web-docs.suqishuo.cn/

部署前：

1. 在 wrangler.toml 中按需修改全局唯一的 Worker name。
2. 在 Cloudflare 创建具有 Workers Scripts: Edit 权限的 API Token。
3. 在 GitHub 仓库 Settings → Secrets and variables → Actions 中添加 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID。
4. 推送到 main，或手动运行 Deploy Cloudflare Worker 工作流。

也可以在安装 Node.js 后本地部署：

npm install
python3 serve-docs.py --export-static dist
npx wrangler deploy

not_found_handling = "single-page-application" 会让 Worker 对前端文档路由返回 index.html。

文档规则

• 文档根目录是启动脚本所在目录，Docker 中是 /docs。
• .git、.gradle、.idea、.pytest_cache、build、.venv、node_modules 会被排除。
• 相对 Markdown 链接会被重写为在线文档链接。
• 相对图片路径会通过服务端 /file/ 路径加载。

Mermaid 示例

flowchart LR
  Start[启动服务] --> Scan[扫描文档]
  Scan --> Render[渲染 Markdown]
  Render --> Pull[后台定时 git pull]
  Pull --> Scan

Loading

常用命令

检查脚本帮助:

./start-docs.sh --help

检查 Python 语法:

python3 -m py_compile serve-docs.py

验证 Docker Compose 配置:

docker compose config

停止 Docker Compose 服务:

docker compose down