Notation
Kristian Gaylord · コーディング · 学習
Notation は、Markdown ファイルのフォルダを Notion に公開する無料のオープンソース CLI だ。リポジトリで書いたドキュメントを 1 コマンドで送り、Notion の検索と AI 機能の上で読ませる。
Notation について
About
Notation とは
Notation は、Markdown ファイルが入ったディレクトリを丸ごと Notion のページに書き込む小さなターミナルツールだ。Rust で書かれ、GPL-3.0 で公開されている。notation ship --src を実行すると、ドキュメントのフォルダを走査し、Notion 側のページツリーを作り直す。
狙いははっきりしている。ドキュメントは、それが説明するコードのそばにあるべきだ。機能追加と同じ pull request で .md を編集すれば、レビュー担当者は差分を見られ、CI に公開処理を任せられる。マージのたびに別のサービスへログインする必要はない。
使う場面を決める制約は 2 つある。出力先は Notion だけなので、公開先は必ず自分のページになる。同期は Markdown から Notion への一方向だけで、リポジトリが唯一の正とされ、Notion 側で打った文字は戻ってこない。
はじめかた
- プロジェクトページの shell スクリプトでバイナリを入れる。実行ファイルは
~/.notationに置かれ、隣に設定ファイルの雛形ができる。 - Notion でドキュメントを載せるページを作り、設定ファイルにそのまま書き写せる名前にする。
- 「設定とメンバー」から内部インテグレーションを作り、シークレットを控える。親ページの「コネクト」でそのインテグレーションを追加し、書き込み権限を与える。
~/.notation/Notation.tomlを開き、インテグレーションのsecretとparent_pageのタイトルを入れる。- リポジトリで
notation ship --src /docs/の/パスを実行する。Notion で結果を確認し、公開サイトにするならページを共有するか独自ドメインを向ける。
AIツール情報
Notationの料金、対応プラットフォーム、性能を簡単に確認できます。
こんな人におすすめ
このツールが最も力を発揮するユーザー、タスク、シーン。
ユーザー
- バックエンドやプラットフォームのエンジニア
- ドキュメントサイトを持たない小さなプロダクトチーム
- サポート、営業、プロダクト担当
タスク
- API リファレンスの公開
- オンボーディング資料の更新
- 社内ランブックの wiki 化
シーン
- すでに Notion を契約していて、ドキュメント用の別サービスは増やしたくない。Notation が足すのは公開の一手間だけだ。
- 更新のたびに別ツールを開く必要があり、ドキュメントが古くなっていた。原稿をリポジトリに戻せば、その往復が消える。
- ドキュメントもコードと同じようにレビューしたい。原稿はバージョン管理下のプレーンテキストなので、普段の pull request の流れがそのまま使える。
主な機能
フォルダを 1 コマンドで公開する
notation ship --src がソースディレクトリをたどり、各ファイルを設定済みの Notion ページへ書き込む。ビルドも、生成したサイトのデプロイもない。マージしてから反映までの距離はコマンド 1 つ分だ。
フォルダ構造がページ構造になる
ディレクトリは子ページに、サブディレクトリは孫ページになる。エディタで見ているツリーが、そのまま読者の見る Notion のツリーだ。フォルダ名を変えれば、次の公開で該当ページ名も変わる。
intro.md で親ページを書く
ドキュメントのルートに intro.md を置くと、その中身は子ページを作らず親ページへ直接書き込まれる。章の入口に、文章とリンクと文脈のあるページができる。空のコンテナに子ページの一覧だけが並ぶことはない。
ページごとのタイトルと絵文字
Markdown の先頭に --title と --emoji を書くと、Notion 側のページ名とアイコンを指定できる。setup.md をロケットの絵文字付きで「Getting Started」として出せる。ファイル名は機械向けのまま、公開されるタイトルは読みやすくなる。
社内 wiki にも公開サイトにも
同じ公開先を、ワークスペース内の非公開のまま使うことも、公開ページとして共有することもできる。独自ドメインを使うなら、公式ドキュメントは Super をフロントエンドに挙げている。notation.so 自身もその構成で動いている。
Notion の検索、AI、書式をそのまま使う
内容が Notion に入れば、検索インデックス、AI の回答、目次、ブロック単位の書式がそのまま手に入る。大量のドキュメントを検索可能にするのは難しい問題で、ここでは他社に任せている。
メリットとデメリット
メリット
- GPL-3.0 の無料オープンソースで、席数もプランもページ上限も気にしなくていい。
- ドキュメントがリポジトリに残るので、コードレビュー、ブランチ、CI が追加設定なしで効く。
- 導入が短い。バイナリを入れ、Notion のインテグレーションを作り、値を 2 つ埋めるだけだ。
- 読む側は Notion で作業する。検索もコメントも AI の回答も、チームがすでに開いているツールに付いてくる。
- 出力は Notion で手作りしたように見える。技術に詳しくない読者でも、Markdown から生成されたとは気づかない。
デメリット
- 同期は一方向だ。Notion 側で直した内容は次の公開で上書きされるので、書く場所はリポジトリだけにしておく必要がある。
- 画像は公開 URL が要る。ローカルのファイルはアップロードされないので、別の場所に置いてリンクを貼る。
- 使う人ごとに Notion アカウント、親ページ、内部インテグレーションのトークンが要る。初回成功までに間違えられる箇所が 3 つある。
- プロジェクトは小さく、最後のコミットは 2024 年 8 月だ。Notion API に破壊的な変更が入れば誰かがバイナリを直す必要があり、インストーラは Windows に対応していない。
よくある質問
Markdown を Notion に公開するためのツールだ。.md をコードリポジトリに置き、notation ship を実行すると、指定した Notion ページの中にページツリーとして現れる。
関連コンテンツ
Notationに関連するツール、スキル、記事を探す。
Notationの代替ツール
Base Code
Base44 (Wix) · コーディング · 生産性向上Base CodeはBase44の共有クラウド開発環境だ。既存のGitHubリポジトリに対する変更をチャットで伝え、プレビューで確認し、プルリクエストとして返せる。
Google EmbeddingGemma 2
Google DeepMind · ライティング · 画像 · コーディングGoogle EmbeddingGemma 2 は 7 億 4000 万パラメータのオープンなモデルで、テキスト、コード、画像、音声、動画フレームを同じ 768 次元空間のベクトルに変え、スマートフォンやノート PC 上で動く。
GitGlow
GitGlow · コーディング · 生産性向上GitGlow は自分のコードと AI エージェントの変更を一つのレビューにまとめるデスクトップ Git クライアントだ。出荷前に、マシンから何が出ていくのかを確かめられる。