docdoc 文档

第一个文档站

完成本任务后，你将得到一个多页面的本地可预览文档站，并走通「写源码 → 构建 → 预览」这条主流程。

前置条件：已完成安装（站内搜索 ?安装）。

操作步骤

  1. 创建源目录并写入首页：

    mkdir my-docs
cat > my-docs/docdoc.json <<'EOF'
{ "title": "My Docs" }
EOF
cat > my-docs/index.md <<'EOF'
# 我的文档

第一页内容。
EOF

  2. 启动本地预览：

    docdoc preview ./my-docs

    终端输出：

    构建完成：1 页
预览服务已启动: http://127.0.0.1:3000/
已监听源目录变化: ./my-docs

  3. 浏览器访问 http://127.0.0.1:3000/，看到渲染后的「我的文档」页面。

  4. 写一章内容（kebab-case 命名，每页以一级标题开头）：

    mkdir my-docs/guides
cat > my-docs/guides/index.md <<'EOF'
# 任务指南

本章收录常用任务的完整操作步骤。


EOF
cat > my-docs/cn/guides/export-report.md <<'EOF'
# 导出报表

## 操作步骤
EOF

    保存后终端输出 重建完成：3 页，刷新浏览器：侧栏出现「任务指南」章节，上一页/下一页按目录顺序翻页。

  5. 需要固定侧栏顺序时，在章节目录放 metadata.docdoc.json：

    { "order": ["export-report.md", "import-data.md"] }

    目录组织、标题来源与排序约定的逐项说明见站内搜索 ?文件与目录。

结果核对清单

  • 页面标题 = 文件第一个一级标题
  • 目录条目顺序与 metadata.docdoc.json 的 order 一致（未声明时按文件名排序）
  • 目录页只写概述与 TOC 宏，没有手工维护的链接列表

补充说明

  • 预览端口被占用时用 --port 换一个：docdoc preview ./my-docs --port 3100
  • 只想要产物不启动服务时，用 docdoc build ./my-docs --output ./site（用途与选项说明见站内搜索 ?build 命令）
  • 源目录也可以没有 docdoc.json：此时整个目录按无清单模式直出为单个文档，站点标题显示为 Docs
  • 站点写好之后发布上线，走站内搜索 ?发布第一个站点