Qiita CLIをWSLで使ってみた感想と運用イメージの話

本稿の内容は執筆時点での環境によります。
特にQiitaCLIは執筆時点では出たばかりなので、将来的には本稿の状況と異なる可能性が高いと思われます。

想定読者（結論）と、本稿でお話しすること

• Qiitaプラットフォームで慣れているなら、あえてQiitaCLIを使う選択肢を選ぶ必要はないと思います。
• Qiitaに投稿した記事のバックアップがしたいならおすすめです
• プラットフォーム・CLIを使うとしても、記事数が多くなった時に管理する方法は別途考えたほうがいいかもしれません。

本稿でお話ししないこと

• 大量の記事をCLIで運用する方法
  • 私も知りたいです
• 既存のQiitaAPIを利用する方法
  • 他の記事とかChatGPT辺りが詳しいです
• マルチポストの具体的な方法
  • 自前で実装するなら結構泥臭い、とだけ言います。

発端

今までQiitaAPIを使った方法で投稿する機能をそれぞれで作っていたような状態でしたが、公式からCLIが出たので使ってみました。
似たような位置づけにQiita Syncがありましたが、使用感が気になります。
最近はQiitaに投稿するために書くというより、markdownで書いたものを投稿する先の一つにqiitaがあるという位置づけで運用しているため私のアカウントからの投稿数自体は少ないですが、手段は多いに越したことはないですね。

Qiita-CLIを使う

実行環境(WSL)

$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 22.04.3 LTS
Release:        22.04
Codename:       jammy

$ npm --version
9.2.0

Qiita-CLIを使える環境を作る

1. npm install @qiita/qiita-cli --save-dev
2. npx qiita init
3. npx qiita login

これだけです。
Qiitaに投稿している記事もローカルに持ってくるので、バックアップ目的ならここまでで完了です。
念のため、作業時点のQiitaCLIのバージョンを置いておきます。

$ npx qiita --version
1.3.0

FrontMatterメモ

npx qiita new (newArticle001)で実行したらpublic/newArticle001.mdが作成され、内容が以下の通り。

---
title: newArticle001
tags:
  - ''
private: false
updated_at: ''
id: null
organization_url_name: null
slide: false
ignorePublish: false
---
# new article body

ぱっと見、何がなんだか分かりにくいので公式と比較。

---
title: newArticle001 # 記事のタイトル
tags:
  - "" # タグ（ブロックスタイルで複数タグを追加できます）
private: false # true: 限定共有記事 / false: 公開記事
updated_at: "" # 記事を投稿した際に自動的に記事の更新日時に変わります
id: null # 記事を投稿した際に自動的に記事のUUIDに変わります
organization_url_name: null # 関連付けるOrganizationのURL名
slide: false # true: スライドモードON / false: スライドモードOFF
ignorePublish: false # true: `publish`コマンドにおいて無視されます（Qiitaに投稿されません） / false: `publish`コマンドで処理されます（Qiitaに投稿されます）
---

シンプルな使い方をしている場合、titleとtagsだけやれば良さそう。
下書きをしたいならignorePublishをtrueにするイメージ。

Qiita CLIを使えると嬉しいこと

• Zennと同じリポジトリで住み分けができます
  • Qiitaはpublic、Zennはarticles,booksディレクトリを使うので、１つのリポジトリで記事が管理できるのは嬉しいですね
  • CLIのオプションでディレクトリ名は変えられます
• 記事のバックアップができます
  • 今まで頑張ってバックアップCIを作っていましたが、これが要らなくなりました。
  • 定期的にバックアップをさせたいならCIはあってもいいかも知れません（Qiitaプラットフォームで投稿する場合など）

運用

QiitaとZennに投稿する

まず前提としてQiitaに投稿する場合はGitHubActionsではなく、npx qiita publish --allを使うことになります。
Zennはpushをトリガーにして後はよろしくやってくれます。
ちなみに、GitHub PagesならGitHub Actionsで制御できます。
このように、デプロイ時は微妙にズレが生じます。

なお、Qiitaに投稿する際はnpx qiita initでpublish.ymlを作っているので、pushする前にリポジトリごとにQIITA_TOKENの設定を忘れずに。

もしQiitaに書いた記事をZennに投稿する、もしくはZennに書いた記事をQiitaにも投稿する（マルチポスト）場合は、それぞれにFrontMatterを設定する必要があります。
こればかりはCIでうまく加工したり、Qiitaに上がっていてZennに上がっていないファイルをチェックする仕組みが必要になります。

記事を管理する

Zennの時にも課題に上げたんですが、GitHubでバックアップする運用だとQiitaの記事もpublicディレクトリに置くだけなので管理が大変です。
プラットフォームがあるのでQiitaに投稿するだけならQiitaのWebエディタを使えばよく、Zennについても同じことが言えます。
とはいえ、プラットフォームを使いつつ記事をバックアップしたい場合はQiitaCLIをバックアップ用に使うと割り切るのが現実的かな、と思います。

運用を考えると、ますますCMSの便利さを痛感することになった印象です。
ただし、QiitaCLI PreviewからQiitaの画像のアップロードリンクにアクセスができるので、CMSによっては画像管理をQiitaに任せるという運用の切り分けができるのは嬉しいです。

【追記】QiitaCLIで新規投稿して、Qiitaプラットフォームで記事を編集するとどうなるか？

運用として望ましい状態ではないですが、せっかくなのでマルチプラットフォーム感を出して運用してみます。
たとえば、２つ以上の端末を使って１つのアカウントを運用する時、どちらかはCLIを使ってどちらかはプラットフォームを使う、というシーンは考えられますね。
この場合にきちんと同期が取れるかどうかは気になるポイントです。

結論だけ言うとnpx qiita pull -fと強制オプションがないと無視されてしまうようです。
ピンポイントにどのファイルを修正したかが分かるならファイルごと削除してpullする事で色々と節約できそうですが、実際そんな運用はやってられない。
とはいえ、git pullではないのでqiitaの内容を正に全てを上書きしてしまうという挙動があり、新しく書いた記事は当然初期化されます。

複数の端末で運用する場合はそれぞれにQiitaCLIを入れるか、あるいはCodeSpace的な場所で運用する方法も検討した方が良いでしょう。

【追記２】QiitaCLIから記事を編集できるか？

公式で大丈夫と言っているので大丈夫でしょう。
ついでに、Qiitaプラットフォームで更新した内容を取り込めるかどうかも検証したいので、追記１部分を手作業で移行しておきます。

この工程でやることは、ローカルで更新してcommit+push。記事の内容が更新されているかを確認します。
ローカル用リンク

→大丈夫でした

【追記３】記事の競合対策を考える（Qiitaとローカルの競合）

ないと思いますが、１つのアカウントを複数人で運用する場合は注意が必要です。
しかし考えられる問題としては、１つのアカウントを１人が複数の端末で運用した場合、特定の記事を同時に変更する可能性は考えられます。
pushした方を正として扱うので、場合によってはgitでいう競合は発生するはずで、競合が発生するケースも考えると、QiitaCLIの環境も一箇所に制限した方がいいかもしれません。
まず真っ先にCodeSpace(GitHub.dev)を使う方法が思いつきますが、残念ながらターミナルが使えないのと、一部拡張機能も動かないのでプレビューも困難です。
こういう時はとりあえずAWSかなぁ、とも思いますがローカルでやれば簡単だしノーコスト、と考えるとなかなか選択肢にしにくい。

最悪の場合はリモートデスクトップとかですかね。
通信負荷やセキュリティはもちろん、昨今上がり続ける電気代などを考えるとあまり使いたくない手段ではあります。

開き直って「記事の編集にQiitaCLIを使わない」という選択肢はあります。

【追記４】ファイルの競合（gitリモートとローカルの競合）

追記１・２において、投稿・編集した時点でupdated_atが更新されます。
publish.ymlを見れば分かりますが、CIで更新した情報をgit pushしているので、ローカルでもgit pullしないとダメです。
つまり、git pullでpublish.ymlの情報を適用し、その上でqiita pull -fで最新の情報を反映させるようにする必要があります。

【追記５】不具合？

大したことではないんですが、WSLでpreviewを実行中にtortoisegitなどでコミットしようとすると、改行コードが一時的に書き換わるようです。
この状態でコミットをしようとすると失敗してしまうので、作業が終わったらpreviewをCtrl+Cなどで終了するようにしましょう。
改行コードが元に戻るので、これで変更したファイルだけcommitできるようになります。

結論（個人の感想）

新しく投稿するだけならQiitaプラットフォームを使うのでも、QiitaCLIでもお好みで使いましょう。
記事数が100を超えた辺りから過去の記事を編集したりする事を考えるなら、外部CMSも検討した方がいいかも知れません。
あるいは「過去の記事は対応しない」という運用もあります。

補足：VSCodeでQiita用mdのプレビュー

CLIでもpreview機能は使えるようですが、vscodeで書くならもっと良い方法があります。

Qiita Markdown Previewを入れた後にいつも通りmarkdownのプレビューをするだけで使えます。

名前: Qiita Markdown Preview
ID: ryokat3.vscode-qiita-markdown-preview
説明: VSCode extension to preview Qiita markdown
バージョン: 0.2.2
パブリッシャー: Ryoji Kato
VS Marketplace リンク: https://marketplace.visualstudio.com/items?itemName=ryokat3.vscode-qiita-markdown-preview

従来のmarkdownプレビューが出来なくなるので、使わない時は拡張機能を無効にしましょう。