跳到主要内容

文档写作规范

本地开发​

npm install      # 首次
npm start        # 本地预览，默认 http://localhost:3000
npm run build    # 生产构建，会检查死链
npm run serve    # 预览构建产物
npm run typecheck

npm run build 会因为死链直接失败（onBrokenLinks: 'throw'），这是刻意的——文档里的链接必须一直有效。

新增一篇文档​

  1. 在 docs/ 下建 .md 文件，路径即 URL：docs/products/foo.md → /docs/products/foo。

  2. 写 front matter：

    ---
    id: foo
    title: Foo
    sidebar_position: 9
    description: 一句话说明，会用作 SEO 描述
    ---

  3. 把文档 id 加进 sidebars.ts 的对应分组（本站侧边栏是手工维护的，不加就不会出现在导航里）。

写作约定​

  • 文档间链接用相对路径加扩展名：[FlowMax](../products/flowmax.md)。这样构建时能校验，重命名文件也能被发现。
  • 链接 static/ 里的静态文件要用 pathname:// 前缀：[Pitch](pathname:///prototypes/traderx-pitch.html)，否则 Docusaurus 会当成路由去解析并报死链。
  • 未定的内容写成 待补充 清单，用 - [ ] 列出具体待决策项，而不是留白。空文档比没有文档更误导人。
  • 状态词统一口径：规划中 / 方案设计中 / 开发中 / 已上线。改了产品页的状态，同步改产品矩阵的表格。
  • 日期写绝对日期（2026-03-22），不要写「上周」「下个月」。

提示框​

:::note 说明 :::
:::tip 建议 :::
:::info 信息 :::
:::caution 注意 :::
:::warning 警告 :::
:::danger 危险 :::

Mermaid 图​

已启用 Mermaid，直接用代码块：

```mermaid
flowchart LR
  A --> B
```

草稿与内部内容​

  • 加 draft: true 让文档只在本地开发时可见，生产构建会跳过。
  • 加 unlisted: true 让文档可访问但不进侧边栏、不进搜索、不进 sitemap。

发布动态​

blog/ 目录挂在 /updates 路由下，用于产品进展和内部通告。新增一篇：

blog/2026-09-10-标题.md

front matter 里的 authors 取自 blog/authors.yml，tags 取自 blog/tags.yml——新作者/新标签要先在这两个文件里登记。