Notation

Notation is a command-line tool that solves a specific problem for developers: it automatically publishes Markdown files from a local repository into a Notion workspace. You write your documentation in Markdown, which lives right next to your code, and Notation handles the conversion and upload. This means your docs are version-controlled and go through the same review process as your code, but end up in a polished, accessible format for everyone. The tool works by taking a directory of Markdown files. It converts the folder structure into a hierarchy of Notion pages and translates the Markdown syntax into Notion's native blocks. It supports headers, code blocks, lists, tables, and links. A key feature is the handling of relative links between Markdown files, which become clickable links between the resulting Notion pages. Notation stands out by being incredibly focused. It is not a full-blown static site generator or a complex documentation platform. It is a simple bridge between a developer's local workflow and the collaborative, user-friendly environment of Notion. The setup involves creating a Notion integration, specifying a parent page in a config file, and running the 'notation ship' command. This tool is most useful for development teams that already use Notion for internal knowledge sharing but want to keep their technical documentation authored in Markdown within their codebase. It eliminates the manual copy-pasting between a code editor and a web-based wiki, making documentation updates as easy as committing code.