Notation
A powerful tool that converts Markdown into Notion pages, featuring integrated AI, advanced search, and formatting capabilities.
About Notation
Notation enables seamless conversion of Markdown files into Notion pages with automatic publishing. You can publish content privately, password-protected, or as a publicly accessible website. Benefit from Notion’s AI, search, and formatting features at no extra cost. Designed to keep documentation close to your codebase, it eliminates the need for separate services or complex frontend frameworks.
How to Use
Create your documentation in Markdown, generate a Notion page, obtain an API key from Notion, store it in ~/.notation/Notation.toml, and execute the command: notation ship --src </path/to/your/docs>.
Features
- Supports CLI options for customizing titles and emojis
- Converts Markdown files into Notion pages
- Integrates Notion's AI, search, and formatting tools
- Automatically creates subpages based on directory structure
Use Cases
- Publishing a public website from Markdown documentation
- Sharing documentation within a Notion workspace
- Maintaining code alongside project documentation
Best For
Technical writersProduct managersTeams managing documentation in NotionSoftware engineersContent creators
Pros
- Utilizes Notion’s AI, search, and formatting features
- Keeps documentation close to source code
- Eliminates the need for separate login systems
- Supports both internal and public documentation
- Simplifies formatting with Markdown
Cons
- Requires a Notion account and API key setup
- Involves configuration via a TOML file
- External hosting needed for images
FAQs
What Markdown features are supported?
Notation supports headers, paragraphs, code blocks, lists (ordered and unordered), tables, links, images (host externally), relative page links within the repo, and directory structures that generate subpages.
How do I configure Notation?
Create a Notation.toml file in ~/.notation/ with your Notion API secret and specify the parent page for publishing.
What are the setup steps?
Create a Notion account, set up a page for documentation, generate an API integration, and connect it to your page by adding your secret key.
Can I publish my documentation publicly?
Yes, you can publish documentation as a public website or keep it private within your Notion workspace.
Do I need hosting for images?
Images must be hosted externally; local images are not supported directly.