Markdown ドキュメントをローカルで管理して Qiita/esa.io に同期する

概要

Qiita および esa.io など Markdown でドキュメントを編集、公開できるサービスはいろいろ存在しますが、ローカルでドキュメントを書いて同期する CLI ツールを作ってみました。

• marksync (GitHub)

ターゲット (こんな人に)

• 使い慣れたエディタで編集したい。
• 公開したドキュメントのマスターを手元で管理したい。
• 複数のサービスに、同じドキュメントを公開したい。(社内と社外とか)
• 細かい修正をちょこちょこして、タイミングを見て反映したい。
• 複数のドキュメントをまとめて直したい。
• 画像など添付ファイルを修正したときにアップロードし直すのが面倒。
• サービスが死んだり見限ったときにすぐに移行できるようにしておきたい。

インストール方法

必須環境

• Java
• npm

インストール

npm で公開してみました(初)。以下でたぶんいけるはず。

npm install -g marksync

環境設定ファイルを作成

ドキュメントが配置されたディレクトリ構造の最上位に .marksync ファイルを作成し、同期するサービスや認証情報を記述しておきます。

Qiita の場合

SERVICE=qiita
QIITA_USERNAME=(Qiitaのユーザー名)
QIITA_ACCESS_TOKEN=(Qiitaのアクセストークン)

アクセストークンは、設定 > アプリケーション > 個人用アクセストークンから発行します。

esa.io の場合

SERVICE=esa
ESA_TEAM=(esa.ioのチーム名)
ESA_USERNAME=(esa.ioのユーザー名)
ESA_ACCESS_TOKEN=(esa.ioのアクセストークン)

アクセストークンは、SETTINGS > Applications > Personal access token から発行します。

Zenn の場合

Zenn は API ではなく GitHub リポジトリ経由で管理されるため、事前にリポジトリを作成して連携しておきます。

SERVICE=zenn
ZENN_USERNAME=(Zennのユーザー名)
ZENN_GIT_DIR=(ローカルに保存するリポジトリパス)
ZENN_GIT_URL=(GitHubリポジトリのURL)
ZENN_GIT_BRANCH=(リポジトリのブランチ名)
ZENN_GIT_USERNAME=(GitHubのユーザー名)
ZENN_GIT_PASSWORD=(GitHubのパスワード)

Personal accesst token を使う場合は、以下のように設定すれば OK。

ZENN_GIT_URL=https://(Personal access token)@github.com/(ユーザー名)/(リポジトリ名).git
ZENN_GIT_USERNAME=(Personal access token)

使い方

サービスからドキュメントを取り込む

以下のコマンドで、サービスに登録されたドキュメントをすべてローカルに取り込むことができます。ただし、ドキュメント内で使われている画像等の添付ファイルは取得されません。

marksync import -o (出力先ディレクトリ)

ドキュメントごとに index.md と marksync.xxx.yml というファイルの入ったディレクトリが作成されます。

ドキュメントの新規作成

フォルダを作成してその中に index.md ファイルを作ります。1 行目は必ず「# (タイトル)」としてください。以下のコマンドでドキュメントに対するメタデータ(marksync.xxx.yml)ファイルを生成します。

marksync new

メタデータを変更する

Qiita の場合

marksync.qiita.yml の以下の内容を編集します。詳細は API ドキュメント を参照してください。

private: true
tags:
- name: "tag"
  versions: []

esa.io の場合

marksync.esa.yml の以下の内容を編集します。詳細は API ドキュメント を参照してください。

tags:
- "tag"
category: "category"
wip: true

Zenn の場合

marksync.zenn.yml の以下の内容を編集します。詳細は Zenn CLIで記事・本を管理する方法 の「記事の作成」を参照してください。

type: "tech"
topics: []
published: false

更新の確認

以下のコマンドで各ドキュメントに更新があるかどうかを確認します。

$ marksync status
  ./docs/doc1: not modified.  ★変更なし
! ./docs/doc2                 ★変更あり
+ ./docs/doc3                 ★新規

ドキュメントの更新がある場合、以下のコマンドで差分を確認できます。

$ marksync diff

同期

以下のコマンドで、サービスにドキュメントを同期(作成/更新)します。

$ marksync update

ツール以外の方法でサービス上のドキュメントが編集されたことが検出された場合、安全のため更新されません。その場合は -f オプションをつけることで強制的に上書きします。

ドキュメントから参照しているローカルファイルは、添付ファイルとして自動的にアップロードすることができます。

• esa.io ではアップロード API を使用してアップロードします。特別な設定は不要です。
• Qiita/Zenn ではファイルをアップロードする API がないため、AWS に自分用のパブリック S3 バケットを準備する必要があります(後述)。設定がない場合、添付ファイルはアップロードされません。

添付ファイルを S3 バケットにアップロードする

アップロード先となる S3 バケットを作成します。(例として hirose-public とします。)

aws s3 mb s3://hirose-public

.marksync に以下のように設定します。

UPLOADER=s3
S3_BUCKET_NAME=hirose-public
S3_PREFIX=qiita
S3_BASE_URL=https://hirose-public.s3-ap-northeast-1.amazonaws.com

AWS アクセス時の認証情報は、AWS CLI 用に設定したものが使われます。

UML 変換

PlantUML で記述したものは図にします。

• esa.io ではそのまま、図として表示されます。
• Qiita/Zenn では画像に変換して添付ファイルとしてアップロードされます。

さいごに

自分用に使うためだけに作っていたツールなので、いろいろ問題あるかもしれません。。
ニーズあるか分かりませんがとりあえず公開してみたところです。フィードバックいただけると幸いです!