Notation

Notation is a small command line tool that takes a directory of Markdown files and pushes it into a Notion page. The repository is written in Rust and released under GPL-3.0. One command, notation ship --src, reads your docs folder and rebuilds the page tree inside Notion.

The idea is docs as code: documentation belongs with the code it describes. You edit .md files in the same pull request as the feature, reviewers see the diff, and CI can run the publish step. Nobody logs into a separate docs service after a merge.

Two constraints shape how you use it. Notion is the only destination, so the publish target is always a Notion page you own. And the sync runs one way, from Markdown into Notion, which means the repo stays the source of truth and edits typed inside Notion don't come back.

Getting Started

1. Install the binary with the shell script from the project page. It writes the executable to ~/.notation and creates a starter config file next to it.
2. Create a Notion page that will hold the docs, and give it a name you can retype exactly in the config.
3. Create an internal integration in Notion under Settings and members, then copy its secret. On the parent page, add that integration under Connections so it gets write access.
4. Open ~/.notation/Notation.toml and fill in two values: the integration secret and the parent_page title.
5. Run notation ship --src /path/to/docs from the repo. Check the result in Notion, then share the page publicly or point a custom domain at it if you want a public site.