docmd 入门模板 (Starter Template)

docmd-template 仓库是启动一个新文档站点的最快方式。它包含一份可用的 docmd.config.json、一个示例页面、一份用于本地开发的 package.json，以及一个预配置的 GitHub Actions 工作流，每次推送时都会自动部署到 GitHub Pages。

快速开始

1. 创建仓库

在 GitHub 上点击 使用此模板 (Use this template)。为您的仓库命名并点击 Create repository。您无需 fork —— 模板会生成一个干净的、独立的副本。

2. 配置站点

在新仓库中打开 docmd.config.json，并更新 title 和 url 字段：

{
  "title": "我的文档",
  "url": "https://username.github.io/repo-name"
}

将 username 和 repo-name 替换为您的 GitHub 用户名和仓库名。

3. 启用 GitHub Pages

每个仓库只需执行一次：

1. 进入 Settings → Pages。
2. 在 Source 下选择 GitHub Actions。
3. 保存。

4. 推送并部署

向 main 推送任意修改。包含的工作流会构建您的站点并自动部署到 GitHub Pages。您的文档将在以下地址上线：

https://<username>.github.io/<repo-name>/

模板包含的内容

.github/
  workflows/
    docs.yml          # 推送到 main 时自动构建并部署
docmd.config.json     # 站点标题、URL 和输出目录
docs/
  index.md            # 您的第一个文档页面
package.json          # 本地开发脚本

本地开发

克隆您的仓库并启动开发服务器：

npm install
npm run dev

站点将在 http://localhost:3000 提供服务，并支持实时刷新。对 Markdown 文件的修改会立即反映出来。

要在本地构建生产版本：

npm run build

编译后的站点默认写入 site/ 目录。

内置的工作流

模板自带 .github/workflows/docs.yml：

name: Docs

on:
  push:
    branches: [main, master]
  workflow_dispatch:

permissions:
  contents: write
  pages: write
  id-token: write

concurrency:
  group: docs
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install
        run: npm install @docmd/core

      - name: Build
        run: npx @docmd/core build

      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./site

      - name: Deploy
        id: deploy
        uses: actions/deploy-pages@v4

工作流直接安装 @docmd/core 而不使用锁文件 —— 这是有意的：模板没有提交 package-lock.json，因此不使用 actions/setup-node 缓存。这让模板保持无依赖，同时仍能稳定部署。

添加您的第一个页面

在 docs/ 中创建一个新的 Markdown 文件：

docs/
  index.md        # 首页
  getting-started.md
  api-reference.md

添加 navigation.json 以控制侧边栏：

[
  { "title": "首页", "path": "/" },
  { "title": "快速开始", "path": "/getting-started" },
  { "title": "API 参考", "path": "/api-reference" }
]

完整的导航配置请参阅 导航配置 (Navigation Configuration)。

自定义域名

要使用自定义域名（例如 docs.example.com）：

1. 更新 docmd.config.json 中的 url 字段：

   { "url": "https://docs.example.com" }
   

2. 在 docs/ 目录下添加一个包含您域名的 CNAME 文件。
3. 在 Settings → Pages → Custom domain 中配置域名。

入门模板 vs. GitHub Action

模板从一开始就让您完全拥有工作流文件和配置的所有权。GitHub Action 更适合在不重构现有仓库的前提下为其添加 docmd 部署。