Notation

Notationは、ドキュメントをコードと一緒に管理したい開発者向けに設計された強力なコマンドラインインターフェース（CLI）ツールです。Markdownのようなシンプルで普遍的な形式でドキュメントを作成することと、Notionのような多機能で協力的なプラットフォームに公開することの間のギャップを埋めます。Notationの核となる哲学は、ドキュメントはそれが記述するコードと共に存在し、同じレビュープロセスを受け、別のサービスにログインすることなく簡単に更新できるべきだというものです。これにより、別のドキュメントウェブサイトを管理したり、フロントエンドフレームワークと格闘したりする複雑さがなくなり、効率化された開発者中心のワークフローが提供されます。

Notationを使用することで、チームはドキュメントが常にコードベースと最新の状態にあることを保証できます。コードがマージされると、対応するドキュメントは単一のコマンドでNotionに公開できます。これにより、他のエンジニアだけでなく、Notionの使用に慣れているプロダクトマネージャー、デザイナー、サポートスタッフなどの非技術的なチームメンバーもドキュメントに簡単にアクセスできます。このツールは、強力な検索、AI機能、豊富なフォーマット、柔軟な共有オプションなど、Notionのすべてのネイティブ機能を活用し、堅牢なドキュメンテーションシステムを無料で提供します。

Notationの使い方

Notationの使用には、ローカル開発環境をNotionワークスペースと統合する簡単なセットアッププロセスが含まれます：

1. インストール：公式ドキュメントで提供されている簡単なcurlコマンドを使用して、Notationバイナリをローカルマシンにインストールします。これにより、ターミナルで`notation`コマンドが利用可能になります。
2. 設定：`~/.notation/`ディレクトリに`Notation.toml`という名前の設定ファイルを作成します。このファイルには、Notion APIシークレットと、ドキュメントを公開したいNotionの親ページのタイトルが保存されます。
3. Notionインテグレーション：Notionワークスペース内に新しい内部インテグレーションを作成する必要があります。これにより、`Notation.toml`ファイルに追加するシークレットAPIキーが生成されます。
4. ページへの接続：Notionで、親ページとして指定したページに移動します。「接続」メニューを使用して、新しく作成したインテグレーションにこのページへのアクセスを許可します。
5. ドキュメントの作成：プロジェクトのリポジトリ内でMarkdownファイルを使用してドキュメントを作成します。ファイルをディレクトリに整理することができ、NotationはそれをNotionのネストされたサブページに変換します。
6. 公開：ターミナルで`notation ship --src `コマンドを実行します。NotationはMarkdownファイルとディレクトリ構造を解析し、Notionワークスペースに対応するページを自動的に作成または更新します。

Notationの主な機能

• MarkdownからNotionへの変換：標準のMarkdownファイルを美しくフォーマットされたNotionページに自動的に変換します。ヘッダー、リスト、コードブロック、テーブル、リンクなどをサポートします。
• ディレクトリ構造の保持：ローカルのディレクトリ構造をNotionのネストされたページとして複製し、複雑なドキュメントの整理を容易にします。
• CLIベースのワークフロー：開発者のコマンドライン環境にシームレスに統合し、自動化されたドキュメント更新のためにCI/CDパイプラインに追加できます。
• カスタムページメタデータ：`--title "マイページ"`や`--emoji 🚀`のような簡単なフラグを使用して、Markdownファイルから直接Notionページのタイトルと絵文字アイコンを設定できます。
• 親ページコンテンツ：特別な`intro.md`ファイルを使用して、別のサブページを作成する代わりに、メインの親ページに直接コンテンツを追加できます。
• Notionのパワーを活用：公開されると、ドキュメントはNotionの高度な検索、組み込みAI機能、共同編集、柔軟な共有オプション（内部、公開、またはウェブサイトとして）の恩恵を受けます。
• 相対リンクの処理：Markdownファイル間の相対リンクを適切なNotionページリンクにインテリジェントに変換し、ドキュメント内でのシームレスなナビゲーションを保証します。

Notationの使用例

Notationは多機能であり、さまざまなドキュメンテーションのニーズに適応できます：

• 内部エンジニアリングWiki：開発チームのための中央集権的なナレッジベースを作成・維持し、ドキュメントは関連するコードのすぐ隣に存在します。
• 公開APIドキュメント：外部開発者向けに、明確でよく構造化されたAPIドキュメントを公開します。Notionページはワンクリックで公開できます。
• ユーザーガイドとマニュアル：非技術的なライターが（Notionを介して）簡単に貢献でき、開発者が（Markdownを介して）簡単に更新できる、ユーザー向けのドキュメントを開発します。
• プロジェクトドキュメント：技術仕様書から会議の議事録まで、すべてのプロジェクト関連ドキュメントを整理し、プロジェクトの開発ライフサイクルと同期させます。
• 個人ナレッジベース：開発者は、個人のメモや技術的な参照を管理し、プライベートなNotionスペースに公開するために使用できます。

Notationの利点

Notationの主な利点は、そのシンプルさと開発者第一のアプローチです。

• コードとしてのドキュメント：ドキュメントをリポジトリに保持することで、標準的な開発ワークフローの一部としてバージョン管理、レビュー、更新が可能です。
• オーバーヘッドの削減：Docusaurusのような複雑な静的サイトジェネレーターを管理・展開したり、Reactのようなフロントエンドフレームワークを学んだりする必要がありません。
• 単一の信頼できる情報源：NotionのドキュメントがリポジトリのMarkdownファイルを直接反映することを保証し、コンテンツの乖離を防ぎます。
• アクセシビリティの向上：非エンジニアが技術ドキュメントに簡単にアクセスして読むことができるようにし、より良い部門横断的なコラボレーションを促進します。
• 費用対効果：ツール自体は無料でオープンソースであり、Notionの無料または既存のプランを活用するため、非常に経済的なソリューションです。

料金プラン

Notationは無料のオープンソースツールです。無料でダウンロードして使用できます。ユーザーは、Notionプランに関連する費用（多くのユースケースはNotionの無料プランで対応可能）または、super.soなどのサードパーティサービスを使用してNotionページをカスタムドメインのウェブサイトに変換する場合の費用のみを負担します。