ドキュメント管理の将来設計

MarkdownのAtom+Git管理のすゝめ

以前から Markdown のドキュメントは Atom Editor + Git で管理しているのですが、結構オススメです。メリットとしてはざっと以下の感じ。

• まず、はじめに Evernote などとの比較で言うと、 Evernote はご存知、保存形態が HTML なので、正直 Evernote オワコンになって、他に移行したくても、結構きついです。
  • ためたドキュメントが多いとなおさら感が・・・
  • ドキュメントの移行は機械的にやることを考えるべきです。 Markdown の方がやりやすい。 Markdown で書くにしても、あまり拡張記法は使わないことです。
• Qiita や他の Markdown でのドキュメントサービスとの比較で言えば、更新履歴などが手元で管理できるのが、やはり将来的な移行を考慮した場合にやりやすいです。
  • API など使えば、最新版のドキュメントは外だしできると思うんですが、履歴まで全部取ってくるのはしんどいですよね。
  • Git で履歴が追える安心感があれば、過去のドキュメントの整理などが思い切って削除したりも余裕です。このあたりは普段の開発と同じです。
• Markdown と Git の相性が非常にいいです。ドキュメントもソースコードと同じでどんどん更新されていくものだから。差分とか見ててわかりやすいです。
• 正直 Git で管理していたら、現時点で最も何とでもなりそう感がする。将来新しい VCS (version control system) が出てきても Git から移行するツールとか提供されそう。
• Editor は、別に Atom でなくてもいいんですが、非常に動作が軽快で、拡張性も高い点が気に入っています。

デメリットとしては、自動で sync とかしてくれないので、手動で commit とか push とかしてかないといけない点です。でも、それすらもメリットに感じます。

Markdown を Atom で管理する上で、オススメな Atom のパッケージを挙げておきます。

• file-icons: ファイルのアイコンがいい感じに表示してくれる
• markdown-preview-plus: Atom は標準で Markdown プレビューが付いてますが、これ入れると数式とかも表示してくれます。
• pinned-tabs: Chrome にもあるやつです。いつも使うファイルはピンしておけます。

手前味噌ですが...

このように Markdown を自前の Git リポジトリで管理するメリットは有り余ります。
ただ、情報共有時などで Qiita などのドキュメントサービスにもやっぱりあげたい時があったのですが、二重管理になるのが嫌だなぁというのがありました。 (結局手動でコピーしたりね・・・)

そこで、ドキュメント管理が Atom + Git で完結するようなパッケージを作成してみました。つまり、各ドキュメントサービスのクライアントアプリ (Qiita でいう kobito みたいな) として、 Atom を使えるということです。この記事も Git管理 して、このパッケージ使って更新かけています。

作成したパッケージはこちらです。

機能 / 使い方

今のところ、以下のような機能を提供しています。

• Import 機能
  • 各サービスの記事一覧をローカルに取り込みます
    • Qiita はユーザ名指定
    • Qiita::Team チーム名とユーザ名指定
    • esa.io はチーム名指定
    • DocBase はドメイン指定
    • Confluence はドメイン、スペース指定
    • WordPress.com / WordPress.org はドメイン指定
    • Backlog はスペース指定
  • 取り込んだ記事はローカルのディレクトリ指定で最新状態に更新できます
  • 各ファイルを指定することで、ファイル指定で最新状態に更新できます
    • Import の際にローカル側で未反映の変更がある場合は、そのファイルは Import をスキップします
• Export 機能
  • ローカルで作成したファイルを個別指定で、各サービスに記事として投稿できます
    • Title も指定できますが、空にしておくとファイル名を自動で使います
  • 既に取り込んだ or 投稿したファイルを個別指定で、ローカルの変更で記事を更新できます

注意点としては、

• 各 API の rate limit があるので、記事数が多かったりすると引っかかるかもしれません
• リモート側の変更はチェックしてないので、他人が更新可能な場合には、その変更を上書きする恐れがあるため、そのようなケースでは Import してから Export してください
• これ大事ですが、 public な情報と private な情報は、別プロジェクトで管理して下さい。便利な分、間違って投稿する恐れがあります...

利用時には、各サービス API のアクセストークンを指定する必要があります。
アクセストークンの取得方法は以下のとおりです。

• Qiita/Qiita:Team
  • https://qiita.com/settings/applications から個人用アクセストークンを発行
• esa.io
  • https://{team}.esa.io/user/applications から個人用アクセストークンを発行
• DocBase
  • https://{domain}.docbase.io/settings/profile から API Token を発行
• WordPress.com
  • OAuth2 Authentication | Developer Resources に記載の "Testing an application as the client owner" を参考にして $access_key を得る
• WordPress.org
  • Application Passwords プラグインをインストールし、ドキュメントに記載の方法で ACCESS_TOKEN を得る
• Confluence
  • https://id.atlassian.com/manage/api-tokens から API Token を発行
• Backlog
  • https://{spaceKey}.backlog.jp/EditApiSettings.action から API Key を発行
• Hatena Blog
  • https://blog.hatena.ne.jp/{hatenaId}/{blogId}/config/detail から API key を取得

設計

設計時に注意した点として、以下があります。

• 各サービスごとに結構特徴があるのですが、それらは設定ファイルにメタ情報として保存、更新系 API の場合は画面上から入力可能にすることで、差異の吸収を図りました
  • Qiita の場合は、シンプルでフラットな構造なので、そのまま単階層に Import するようにしました
  • esa.io は、 category が事実上ディレクトリのような扱いなので、ローカルでも Import 時はその構成を再現するようにしました
  • DocBase の場合は、 group と scope というのがあり、これらはメタ情報として制御可能にしました
  • Confluence の場合は、本体が HTML として保存されているため、 Markdown として出力できるオプションを付けました
  • Backlog の場合は Markdown or Backlog wiki 記法を選択可能なので、プロジェクト設定から取得するようにしました
  • 各サービスとも tag はメタ情報として制御可能にしました
  • 各サービスとも WIP 状態は未実装です
• ポータブルにするため、設定ファイルは ~/.atom ではなく、 Atom でプロジェクトとして開いたディレクトリルートに作るようにしています
  • これによって例えば git 保存して持ち運びできるようになります。
  • アクセストークンについては、パッケージの設定で非保存可能にしています (別ファイル保存にしているので gitignore に入れることでも対応可能です)
• ファイルと各サービスとのヒモ付は 1:m 対応が可能なようにしました (同一ファイルを Qiita や esa.io など複数サービスに投稿可能です)

最後にお願い

ソースコードは MIT で公開しています。

割と突貫工事で作ったのと JS の async に慣れてないのとで荒削りのコードですが、まだまだ改善できることは多いので、ぜひフィードバック頂けるとモチベーションになります！
他のサービスとの連携とかでも嬉しいです！

• Issue
• 可能なら Pull Request