Notation
Publish markdown docs to Notion with ease
What is Notation? Complete Overview
Notation is a developer-friendly tool that bridges the gap between markdown documentation and Notion. It allows developers to write documentation in markdown format and automatically publish it to Notion, where it can be shared internally or turned into a public website. The tool is designed for developers who want to keep documentation close to their codebase while leveraging Notion's powerful formatting, search, and AI capabilities. Notation addresses the pain points of managing documentation separately from code repositories and simplifies the documentation process by eliminating the need for complex frontend frameworks or separate documentation services.
Notation Interface & Screenshots
Notation Official screenshot of the tool interface
What Can Notation Do? Key Features
Markdown to Notion Conversion
Notation seamlessly converts markdown files into Notion pages, preserving the structure and formatting. This includes headers, paragraphs, code blocks, lists, tables, links, and images (hosted externally). Relative page links in markdown are converted into Notion page links, and directory structures become subpages in Notion.
Simple Configuration
Setup is straightforward with a Notation.toml configuration file where you specify your Notion API key and the parent page name for your documentation. This minimal configuration makes it easy to get started quickly.
Flexible Deployment Options
Documentation can be kept internal to your Notion workspace, published as a public Notion page, or deployed as a full website using services like super.so. This flexibility caters to different team needs and documentation purposes.
Special File Handling
Notation provides special handling for intro.md files, allowing content to be displayed directly on the parent page rather than as a subpage. This feature helps create more intuitive documentation structures.
CLI Customization
Through command-line arguments, you can customize page titles and emojis directly in your markdown files, adding personality and clarity to your documentation pages in Notion.
Best Notation Use Cases & Applications
Technical Documentation
Development teams can maintain API documentation, architecture decisions, and onboarding guides in markdown alongside their codebase, then automatically sync them to a shared Notion workspace for the entire team to access.
Public Knowledge Base
Companies can create public-facing documentation websites by publishing markdown content to Notion and then using services like super.so to host it, combining the convenience of markdown authoring with Notion's publishing capabilities.
Product Documentation
Product teams can collaborate with engineers on documentation in markdown format within the code repository, then publish polished versions to Notion for non-technical stakeholders like product managers and customers to access.
How to Use Notation: Step-by-Step Guide
Install Notation by running the provided curl command in your terminal. This will download and install the Notation binary to your ~/.notation directory.
Create a Notion API integration through your Notion account settings and obtain the secret key. Configure your Notation.toml file with this secret and specify your parent page name.
Connect your Notion parent page to the integration you created by selecting your integration from the Connections menu in the page settings.
Write your documentation in markdown format following Notation's supported syntax. Organize your files in directories as needed to create your desired page hierarchy.
Run the 'notation ship' command with the path to your documentation directory as the source. Notation will process your markdown files and publish them to your specified Notion page.
Access your documentation in Notion, where you can take advantage of Notion's native features like search, formatting, and table of contents, or publish it as a public website if desired.
Notation Pros and Cons: Honest Review
Pros
Considerations
Is Notation Worth It? FAQ & Reviews
Notation supports headers, paragraphs, code blocks, lists (ordered and unordered), tables, links, and images (hosted externally). It also supports relative page links and converts directory structures into Notion subpages.
Create a Notation.toml file in your ~/.notation directory containing your Notion API secret and the name of your parent page. Then connect your Notion page to your integration through the page settings.
Yes, you can publish your documentation as a public Notion page or use services like super.so to create a full website from your Notion content.
You can create an issue on the Notation GitHub repository for support. The maintainer actively monitors and responds to issues.