一行命令发布
写好 Markdown 后运行 notation ship --src，指向文档所在目录，内容就会被推送到 Notion 的指定页面，不需要手动复制粘贴或再登一套文档后台。
价格官网未公开定价与免费额度
平台Web / API / CLI
归类办公效率
收录2025-01-01
复核2025-01-01
编辑评分
4.4 / 5
★★★★☆
Notation编辑总结
Notation 是一个命令行工具，让工程师把写好的 Markdown 文档直接推送到 Notion 页面，无需另外登录一套文档服务。文档随代码一起提交、审查，发布后即可用上 Notion 内置的 AI、搜索与排版能力。它支持把文档留在团队内部工作区，也可以发布成公开页面或配合 super.so 部署成完整网站。自己的文档站就是用它管理的。
Notation是什么？
Notation 由个人开发者维护，定位是解决「文档和代码分家」的问题。作者在官网上写下的设计哲学很直接：文档描述的是代码，就该和代码住在一起、一起提交；不想为了更新文档再登录另一套在线服务；不想再碰 React 之类的框架；同时也希望非工程师的同事能直接读到文档。
它的做法是让你继续用 Markdown 写作，然后通过一条命令把内容推到 Notion。推上去之后可以只是团队内部的 Notion 工作区页面，也可以发布成公开页面，或者用 super.so 做成一个完整网站——notation.so 自己就是这么搭起来的。文档进入 Notion 后，搜索、AI 和排版这些能力都直接沿用 Notion 已有的。
用法分角色：写文档的工程师只需要在仓库里写 Markdown、配好一个 Notation.toml 和 Notion API Key，然后运行 notation ship --src 指向文档目录；读文档的产品、运营同事则在 Notion 里看，用 Notion 自带的搜索和 AI 找内容，不需要装任何东西。
Notation核心功能
目录即页面层级
仓库里的任意目录结构会被映射成 Notion 的子页面、孙页面，文件和页面一一对应，不用另建一套目录说明。
intro.md 直挂父页
目录里放一个 intro.md，这段内容不会生成子页面，而是直接显示在父页面顶部。适合写模块总览或模块说明，避免点进去才看到一段导语。
页面参数标记
支持在 Markdown 文件顶部用 title 和 emoji 两个参数，分别指定该页在 Notion 中的标题与页面图标，发布时自动带上，不用在 Notion 里逐页改。
三种发布去向
文档可以只留在团队自己的 Notion 工作区内，也可以发布成公开的 Notion 页面，或者配合 super.so 部署成完整网站，按对外程度自己选。
复用 Notion 能力
内容进入 Notion 后，AI、搜索和排版直接沿用 Notion 自带的，文档站不需要自己再实现一套检索或 AI 问答。
Markdown 语法支持
支持标题、段落、代码块、有序与无序列表、表格、链接；图片需要自己托管后写入链接，本地图片不会随文档一起上传。
仓库内页互链
Markdown 里指向同一仓库其他文档的相对链接，发布后会自动转成 Notion 的页面链接，跨页跳转不用手工替换成外链。
Notation值不值得用？
如果你已经在用 Notion 做团队知识库，又希望文档跟着代码走、走代码审查流程，Notation 是刚好卡在这个缝隙里的工具：仓库里写 Markdown，一条命令推到 Notion，读完文档的人直接用 Notion 的搜索和 AI。仓库自带的文档站、又不想再维护一套独立站点的话，它也省事。但要注意两点——图片必须自己托管再写链接，本地图片不会自动上传；安装和配置落在用户目录下的 ~/.notation，需要每台机器单独配一次 API Key。文档面向外部读者、需要复杂主题或大规模站点时，Docusaurus 这类方案更合适。
建议选它的情况
- 团队已经把 Notion 当作知识库，想让代码文档也进同一个地方
- 希望文档和代码一起提交、一起走 CI 与评审流程
- 不想再维护一套独立的文档站点或前端框架
- 需要把内部文档对外发布成公开页面或完整网站
不建议选它的情况
- 文档里有大量本地图片，不想额外找图床托管
- 团队不使用 Notion，或不允许文档存到第三方工作区
- 需要复杂主题定制与大规模站点结构
Notation使用建议
入门先把路子走对
- 先建父页面在 Notion 里新建一个页面作为文档根，给它起一个在空间内唯一的名称，并把名字写进 Notation.toml，发布时才知道往哪儿推。
- 建内部集成拿密钥在 Notion 首页右上角进 Settings & members，再到 Connections 里 develop or manage integrations，新建集成时类型选 internal，拿到 secret 后填进 Notation.toml。
- 别忘关联页面光有密钥还不够，要回到父页面的右上角三个点，进 Connections 把这个集成连上，否则发布会提示找不到可写入的页面。
- 先跑一小段第一次先拿一两个 Markdown 文件试发布，确认标题、层级和链接都对，再整目录推，避免结构不对时反复清理 Notion 页面。
进阶省时间也省钱
- 用 intro.md 写总览在子目录里放 intro.md，内容会显示在父页面而不是新开子页，适合给每个模块写一段总览，读者不用点进去才知道这目录讲什么。
- 图片先托管Notation 不会上传本地图片，把图放到可公开访问的地址后，在 Markdown 里写图片链接，发布过去才能正常显示。
- 标题和图标写进文件头在 Markdown 顶部用 title 和 emoji 两个参数指定页面标题与图标，省去在 Notion 里逐页手工改，页面多时差别很明显。
- 靠相对链接串目录跨文档引用同仓库的其他文件时写相对路径，发布后会自动变成 Notion 页面链接；写死外链的话域名一换就全断了。
Notation适合谁用？
后端与基础架构团队
推荐文档在仓库里和代码一起改、一起评审，发布后同事在 Notion 里查，省掉同步文档站的额外流程。
已用 Notion 的知识库团队
推荐团队知识本来就沉淀在 Notion，把工程文档也推进同一个空间，搜索和 AI 问答可以覆盖全部内容。
需要对外发文档的产品团队
推荐可以发布成公开 Notion 页面，或用 super.so 做成完整网站，按对外程度选择，不必另建站点。
文档图片较多的团队
有条件本地图片不会随文档上传，必须自己找地方托管再写链接，图多的话前期整理成本不低。
不用 Notion 的团队
不推荐整套流程依赖 Notion 页面与 API Key，不使用 Notion 的情况下没有可落地的路径。
Notation优点和缺点
优点
- 文档写在仓库里，能跟着代码一起提交和评审
- 一条 notation ship 命令即可把整个目录推到 Notion
- 目录结构自动映射成 Notion 子页面层级
- 进入 Notion 后直接复用其 AI、搜索和排版
- 支持内部、公开页面、super.so 网站三种发布去向
- 支持标题、表格、代码块与仓库内相对链接互转
缺点
- 本地图片不会上传，需自行托管后写链接
- 安装与配置位于用户目录，需逐台机器配置
- 依赖 Notion 账号与 API Key，绑定单一平台
- 官网未说明文档数量或仓库规模的使用上限
Notation常见问题
Notation 怎么用？＋
先在仓库里写好 Markdown，再在 Notion 建一个页面作为文档根，从 Notion 拿一个 API Key 填进 ~/.notation/Notation.toml，最后运行 notation ship --src 指向文档目录，内容就会推送到 Notion，之后用 Notion 的搜索、AI 和目录浏览。
支持哪些 Markdown 语法？＋
标题、段落、代码块、有序与无序列表、表格、链接都支持，还支持指向同一仓库其他文档的相对链接（会转成 Notion 页面链接），以及任意层级的目录结构，会对应生成子页面、孙页面。图片需要自己托管后把链接写进文档。
文档可以只给团队内部看吗？＋
可以。发布目标可以是团队自己的 Notion 工作区，只有被授权的成员能看；也可以发布成公开的 Notion 页面，或者配合 super.so 部署成一个完整网站，按对外程度自己选。
需要写前端或部署网站吗？＋
不需要。明确说不想让人再折腾 React 或自己部署站点，你只要写 Markdown，剩下的交给 Notion；确实想要独立域名和完整站点形态时，再选 super.so 那条路径。
页面标题和图标能自定义吗？＋
可以，在 Markdown 文件顶部用 title 和 emoji 两个参数指定，分别对应 Notion 里的页面标题和页面图标，发布时自动带上，不需要在 Notion 里逐页修改。
怎么让某个目录的内容显示在父页面？＋
在该目录下放一个 intro.md，这段内容不会生成单独的子页面，而是直接显示在父页面上方，适合写模块总览。例如一个目录下有 intro.md 和其他几个文档，intro.md 的内容会留在父页，其余文档各成一个子页面。
和 Docusaurus 这类文档站比怎么选？＋
官网在讲设计理念时直接点名 Docusaurus，认为它过于复杂、需要处理 React 和站点部署。如果你的诉求是文档跟着代码走、让不写代码的同事也能读，Notation 更轻；如果要做主题高度定制、面向外部读者的大型站点，Docusaurus 这类方案更合适。
Notation竞品对比
| 工具 | 编辑评分 | 价格 | 核心功能 | 平台 |
|---|---|---|---|---|
| Notation本工具 | 4.4 | 官网未公开定价与免费额度 | 一行命令发布；目录即页面层级；intro.md 直挂父页；页面参数标记 | Web / API / CLI |
| Docusaurus本工具 | — | 未标价 | 官网点名它过于复杂，需要处理 React 与站点部署，定位更重的文档站框架 | — |
| super.so本工具 | — | 未标价 | Notation 支持的发布去向之一，可把 Notion 页面部署成完整网站，notation.so 本身就是这么做的 | — |
如果诉求是文档跟代码住在一起、不想维护前端框架，选 Notation：写 Markdown、跑一条命令推到 Notion，读完的人直接用 Notion 的搜索和 AI。如果要做主题高度定制、面向外部读者的大型独立文档站，Docusaurus 这类框架更合适，代价是要处理 React 和站点部署。想要独立域名和完整网站形态又不想自己搭前端时，可以在 Notation 的基础上接 super.so，notation.so 自己就是这么部署的。
