Notation

Notation is a powerful command-line interface (CLI) tool designed for developers who want to maintain their documentation alongside their code. It bridges the gap between writing documentation in a simple, universal format like Markdown and publishing it on a versatile, collaborative platform like Notion. The core philosophy behind Notation is that documentation should live with the code it describes, be subject to the same review processes, and be easy to update without logging into separate services. It eliminates the complexity of managing separate documentation websites or wrestling with frontend frameworks, offering a streamlined, developer-centric workflow.

By using Notation, teams can ensure their documentation is always up-to-date with their codebase. When code is merged, the corresponding documentation can be published to Notion with a single command. This makes the documentation accessible not only to other engineers but also to non-technical team members like product managers, designers, and support staff who are comfortable using Notion. The tool leverages all of Notion's native features, including its powerful search, AI capabilities, rich formatting, and flexible sharing options, providing a robust documentation system for free.

How to use Notation

Using Notation involves a straightforward setup process that integrates your local development environment with your Notion workspace:

1. Installation: Install the Notation binary to your local machine using a simple curl command provided in the official documentation. This makes the `notation` command available in your terminal.
2. Configuration: Create a configuration file named `Notation.toml` in the `~/.notation/` directory. This file will store your Notion API secret and the name of the parent page in Notion where you want to publish your documentation.
3. Notion Integration: You need to create a new internal integration within your Notion workspace. This will generate a secret API key that you'll add to your `Notation.toml` file.
4. Connect to Page: In Notion, navigate to the page you designated as the parent page. Use the 'Connections' menu to grant your newly created integration access to this page.
5. Write Documentation: Write your documentation in Markdown files within your project's repository. You can organize files in directories, which Notation will convert into nested subpages in Notion.
6. Publish: Run the command `notation ship --src ` in your terminal. Notation will parse your Markdown files and directory structure, and then automatically create or update the corresponding pages in your Notion workspace.

Core Features of Notation

• Markdown to Notion Conversion: Automatically converts standard Markdown files into beautifully formatted Notion pages. It supports headers, lists, code blocks, tables, links, and more.
• Directory Structure Preservation: Replicates your local directory structure as nested pages in Notion, making it easy to organize complex documentation.
• CLI-based Workflow: Integrates seamlessly into the developer's command-line environment and can be added to CI/CD pipelines for automated documentation updates.
• Custom Page Metadata: Allows you to set the Notion page title and emoji icon directly from your Markdown file using simple flags like `--title "My Page"` and `--emoji 🚀`.
• Parent Page Content: A special `intro.md` file can be used to add content directly to the main parent page, rather than creating a separate subpage.
• Leverages Notion's Power: Once published, the documentation benefits from Notion's advanced search, built-in AI features, collaborative editing, and flexible sharing options (internal, public, or as a website).
• Relative Link Handling: Intelligently converts relative links between Markdown files into proper Notion page links, ensuring seamless navigation within your documentation.

Use Cases for Notation

Notation is versatile and can be adapted for various documentation needs:

• Internal Engineering Wikis: Create and maintain a centralized knowledge base for your development team, with documentation living right next to the relevant code.
• Public API Documentation: Publish clear, well-structured API documentation for external developers. The Notion page can be made public with a single click.
• User Guides and Manuals: Develop user-facing documentation that is easy for non-technical writers to contribute to (via Notion) and for developers to update (via Markdown).
• Project Documentation: Keep all project-related documents, from technical specifications to meeting notes, organized and in sync with the project's development lifecycle.
• Personal Knowledge Base: Developers can use it to manage their personal notes and technical references, publishing them to a private Notion space.

Advantages of Notation

The primary advantage of Notation is its simplicity and developer-first approach.

• Documentation as Code: By keeping docs in the repository, they can be version-controlled, reviewed, and updated as part of the standard development workflow.
• Reduced Overhead: Eliminates the need to manage and deploy complex static site generators like Docusaurus or learn frontend frameworks like React.
• Single Source of Truth: Ensures that the documentation in Notion is a direct reflection of the Markdown files in the repository, preventing content drift.
• Enhanced Accessibility: Makes technical documentation easily accessible and readable for non-engineers, fostering better cross-functional collaboration.
• Cost-Effective: The tool itself is free and open-source, and it leverages the free or existing tiers of Notion, making it a highly economical solution.

Pricing and Plans

Notation is a free, open-source tool. It is available for download and use at no cost. Users are only subject to the costs associated with their Notion plan (many use cases can be served by Notion's free plan) or any third-party services they might use to turn their Notion page into a custom-domain website, such as super.so.