Notation

Purpose

Notation is a command-line tool that publishes Markdown documents to Notion, with the core goal of letting documents be managed in the same repository as code. It solves the problem of "after merging and deploying code, there is no need to log in to a separate service to update documentation."

Main Capabilities

• Automatically publishes Markdown files to Notion pages and generates the corresponding subpage structure.
• Leverages Notion's built-in AI, search, and formatting features without having to implement them yourself.
• Supports publishing documents as an internal knowledge base (private Notion workspace) or as public pages/websites.
• Supports rendering content directly onto a parent page: if an intro.md file exists in the directory, the contents of that file are displayed directly on the parent page instead of creating a subpage.
• Supports parameters passed in the form of CLI flags within Markdown files: title (page title), emoji (page icon).
• Supported Markdown features include: ordered lists, unordered lists, images (must be hosted yourself and provided as links), relative page links (links to other pages in the same repository are converted to Notion page links), arbitrary directory structures (converted to subpages, sub-subpages, etc.).

How to Use

1. Install the Notation binary into the ~/.notation directory.
2. Edit the configuration file ~/.notation/Notation.toml.
3. Create a page in Notion to host the documentation, and note the page name.
4. Create an internal integration in Notion, obtain the API key, and enter it into Notation.toml.
5. Connect that Notion page to the newly created integration.
6. Run the command: notation ship --src </path/to/you/docs>
7. View the documentation in Notion and use built-in features such as AI search, formatting, and table of contents.

Detailed configuration steps:

• Register a Notion account and create a page to host the documentation, and give that page a name.
• Write that page name into Notation.toml (it must be unique within the workspace).
• In Notion's "Settings & members", go to "Connections" -> "Develop or manage integrations", create a new integration, name it, select a workspace, and choose internal as the type.
• Obtain the integration secret and enter it into Notation.toml.
• Return to the parent Notion page, click the three dots in the upper right corner, go to "Connections", find the newly created integration, and click to connect.

Applicable Scenarios

• Development teams want to keep documentation and code in the same repository and follow the same review and CI processes.
• Want documentation updates to happen without leaving the code repository or logging in to an additional service.
• Want non-engineers (such as users and product managers) to be able to read the documentation easily.
• Want the documentation to be highly searchable by reusing Notion's search capabilities.
• Want a publishable documentation site without using React or deploying a separate website.
• Suitable for internal documentation management or public documentation publishing.

Limitations

• Images cannot be local files; they must be hosted yourself and provided as links.
• A Notion account is required, and you need to create an internal integration and configure the API key.
• Basic command-line operation skills are required.
• The official materials do not provide information about pricing, cost, platform support scope, specific results, or performance.
• The official materials do not provide information about support for formats other than the Markdown features listed above.