Notation

Notation for Documentation and Notion Publishing is an integrated approach to writing and publishing documentation by keeping the docs in markdown within the codebase and publishing them directly to Notion or via public websites. It emphasizes a seamless workflow where documentation lives with the code, is searchable, and benefits from Notion's AI, search, and formatting features. The tool provides a CLI interface (notation) to ship markdown docs to Notion, configure a Notion integration, and manage how documentation is surfaced to end users.

How Notation Works

• Write documentation in plain markdown alongside your code.
• Create a Notion page to host your documentation and obtain an API key for Notion.
• Configure the Notation.toml file with your Notion API secret and the parent page name.
• Run notation ship to publish your docs to Notion, where you can leverage Notion's features like AI search, formatting, and table of contents.
• Optionally, ship the docs as a public website using integrations like Super.so or similar tooling.

Getting Started

1. Install the notation tool and place the binary in your PATH.
2. Edit ~/.notation/Notation.toml to include your Notion secret and a unique parent_page name.
3. Create a Notion integration in your Notion workspace and paste the secret into Notation.toml.
4. Run notation ship --src </path/to/your/docs> to publish.
5. View the docs in Notion, with optional public website deployment.

Deployment Options

• Internal Notion workspace documentation
• Public Notion page hosting
• Full website deployment via services like super.so

FAQ / Tips

• The parent_page in Notation.toml determines where the new pages will appear in Notion.
• You can include an intro.md at the root to render on the parent page directly.
• You can pass CLI arguments like --title and --emoji to customize page metadata when shipping.

Safety and Privacy

• The workflow relies on a Notion integration token; keep your secret secure and do not expose it publicly.
• Documentation content remains within Notion with the published surface depending on your Notion sharing settings.

Core Features

• Markdown-based documentation workflow integrated with code
• Publish docs directly to Notion from a local Notation setup
• Notion integration with API secret management via Notation.toml
• Built-in Notion page hierarchy control through parent_page and intro.md
• Optional deployment of docs as a public website via external services
• AI-enhanced search and rich formatting capabilities via Notion
• Lightweight, no heavy frontend tooling or separate CMS required

How to Use Notation

1. Write your documentation in markdown in a repo, using intro.md for direct parent content if desired.
2. Create a Notion integration and obtain a secret key.
3. Place the secret and your target parent page name in ~/.notation/Notation.toml under the [notion] section.
4. Run notation ship --src /path/to/docs to publish to Notion.
5. Access the docs in Notion, use AI search, and share or publish as needed.