Notation

What is Notation?

Notation is a tool that allows you to write documentation in Markdown and automatically publish it to Notion. This lets you leverage Notion's AI capabilities, search functionality, and formatting options for your documentation. It simplifies documentation management by keeping it close to the code and streamlines the publishing process.

How to use Notation?

1. Write your documentation in Markdown.
2. Create a Notion page to host your documentation.
3. Get an API key from Notion.
4. Place the API key in a ~/.notation/Notation.toml file.
5. Run notation ship --src </path/to/you/docs>.
6. View your documentation in Notion with AI search and formatting.

Key Features:

• Markdown Support: Write documentation using standard Markdown syntax.
• Automatic Publishing: Easily publish your Markdown documentation to Notion.
• Notion Integration: Leverage Notion's AI, search, and formatting capabilities.
• Flexible Deployment: Keep documentation internal, publish as a Notion page, or deploy as a full website using tools like Super.so.
• intro.md: Ship content to the parent page directly using an intro.md file.
• Arguments: Set the title and emoji of the page via CLI flags in your Markdown file.

Why is Notation important?

Notation addresses several pain points in documentation management:

• Keeps documentation close to the code, promoting better maintenance.
• Avoids the need for separate documentation services.
• Simplifies the publishing process.
• Enables the use of Notion's powerful features for documentation.

Configuration:

To configure Notation, create a Notation.toml file alongside the notation binary (usually in ~/.notation/).

## ~/.notation/Notation.toml

[notion]
secret = ""
## this is the title of the page that will host your new documentation
parent_page = ""

Set up a Notion account, create a page to host your documentation, and configure the integration to get started. Detailed instructions are available in the full documentation. This makes it easy for anyone to contribute to and maintain the documentation.

Where can I use Notation?

Notation is ideal for:

• Software projects requiring clear and maintainable documentation.
• Teams using Notion for internal knowledge management.
• Individuals who prefer Markdown for writing documentation.

Best way to use Notation?

To get the most out of Notation, ensure your Markdown files are well-structured and organized. Use the intro.md feature to add content directly to the parent page. Take advantage of Notion's AI and search features to improve discoverability.