Notation

Notation 是一款功能强大的命令行界面（CLI）工具，专为希望将文档与代码一同维护的开发者设计。它弥合了使用像 Markdown 这样的简单通用格式编写文档与将其发布到像 Notion 这样功能多样、协作性强的平台之间的鸿沟。Notation 的核心理念是，文档应与其描述的代码共存，接受相同的审查流程，并且无需登录独立服务即可轻松更新。它消除了管理独立文档网站或与前端框架作斗争的复杂性，提供了一个简化的、以开发者为中心的工作流程。

通过使用 Notation，团队可以确保其文档始终与代码库保持最新。当代码合并时，相应的文档可以通过一个命令发布到 Notion。这使得文档不仅对其他工程师可见，也对习惯使用 Notion 的非技术团队成员（如产品经理、设计师和支持人员）开放。该工具利用了 Notion 的所有原生功能，包括其强大的搜索、AI 功能、丰富的格式和灵活的共享选项，免费提供了一个强大的文档系统。

如何使用 Notation

使用 Notation 涉及一个简单的设置过程，将您的本地开发环境与您的 Notion 工作区集成：

1. 安装： 使用官方文档中提供的简单 curl 命令将 Notation 二进制文件安装到您的本地计算机。这使 `notation` 命令在您的终端中可用。
2. 配置： 在 `~/.notation/` 目录中创建一个名为 `Notation.toml` 的配置文件。此文件将存储您的 Notion API 密钥和您希望发布文档的 Notion 父页面的名称。
3. Notion 集成： 您需要在您的 Notion 工作区内创建一个新的内部集成。这将生成一个秘密 API 密钥，您需要将其添加到您的 `Notation.toml` 文件中。
4. 连接到页面： 在 Notion 中，导航到您指定为父页面的页面。使用“连接”菜单授予您新创建的集成访问此页面的权限。
5. 编写文档： 在您项目的存储库中，使用 Markdown 文件编写您的文档。您可以将文件组织在目录中，Notation 会将其转换为 Notion 中的嵌套子页面。
6. 发布： 在您的终端中运行命令 `notation ship --src `。Notation 将解析您的 Markdown 文件和目录结构，然后自动在您的 Notion 工作区中创建或更新相应的页面。

Notation 的核心功能

• Markdown 到 Notion 转换： 自动将标准的 Markdown 文件转换为格式精美的 Notion 页面。它支持标题、列表、代码块、表格、链接等。
• 目录结构保留： 将您的本地目录结构复制为 Notion 中的嵌套页面，便于组织复杂的文档。
• 基于 CLI 的工作流程： 无缝集成到开发者的命令行环境中，并可添加到 CI/CD 管道中以实现文档自动更新。
• 自定义页面元数据： 允许您直接从 Markdown 文件中使用简单的标志（如 `--title "我的页面"` 和 `--emoji 🚀`）设置 Notion 页面的标题和表情符号图标。
• 父页面内容： 可以使用一个特殊的 `intro.md` 文件将内容直接添加到主父页面，而不是创建一个单独的子页面。
• 利用 Notion 的强大功能： 一旦发布，文档将受益于 Notion 的高级搜索、内置 AI 功能、协作编辑和灵活的共享选项（内部、公共或作为网站）。
• 相对链接处理： 智能地将 Markdown 文件之间的相对链接转换为正确的 Notion 页面链接，确保文档内的无缝导航。

Notation 的使用案例

Notation 功能多样，可适应各种文档需求：

• 内部工程维基： 为您的开发团队创建和维护一个集中的知识库，文档就存放在相关代码旁边。
• 公共 API 文档： 为外部开发者发布清晰、结构良好的 API 文档。只需单击一下，即可将 Notion 页面公开。
• 用户指南和手册： 开发面向用户的文档，非技术作者可以轻松地（通过 Notion）贡献内容，开发者也可以轻松地（通过 Markdown）更新。
• 项目文档： 将所有与项目相关的文档（从技术规范到会议记录）保持井然有序，并与项目的开发生命周期同步。
• 个人知识库： 开发者可以用它来管理个人笔记和技术参考，并将其发布到私人的 Notion 空间。

Notation 的优势特点

Notation 的主要优势在于其简单性和开发者优先的方法。

• 文档即代码： 通过将文档保存在存储库中，它们可以作为标准开发工作流程的一部分进行版本控制、审查和更新。
• 减少开销： 无需管理和部署像 Docusaurus 这样的复杂静态网站生成器，也无需学习像 React 这样的前端框架。
• 单一事实来源： 确保 Notion 中的文档是存储库中 Markdown 文件的直接反映，防止内容不一致。
• 增强可访问性： 使技术文档易于非工程师访问和阅读，促进更好的跨职能协作。
• 成本效益高： 该工具本身是免费和开源的，并且它利用了 Notion 的免费或现有套餐，使其成为一个非常经济的解决方案。

定价和计划

Notation 是一款免费的开源工具。它可以免费下载和使用。用户只需承担其 Notion 套餐相关的费用（许多用例可以通过 Notion 的免费套餐满足），或他们可能用来将其 Notion 页面转换为自定义域名网站的任何第三方服务（如 super.so）的费用。