自分のエディタで記事投稿ができる、Qiita CLIの使い方 #Qiita

Qiita CLIとは

Qiita CLIとは、手元の環境で記事の執筆・プレビュー・投稿ができるツールです。
Qiita CLIを使うことで、普段ご自身で使っているエディタなどを使って記事の執筆・投稿がしやすくなります。

このツールでは、コマンドラインやプレビュー画面での記事作成、更新・投稿を可能にします。
また、GitHub Actionsを用いてGitHubを介した記事投稿・更新も可能です。

プレビューは以下のように確認することができます。

このようにエディタで書いた記事をプレビューすることができます。

サイドバーでは未投稿の記事だけではなく、投稿済みの記事や編集中の記事なども確認、編集することが可能です。（プレビューを起動することで、Qiitaにすでに投稿した記事を自動でダウンロードできます）

Qiita CLI の利用方法について

不具合やご意見などございましたらQiita Discussionsへご投稿ください。

1. 事前準備

Qiita CLI を使うには Node.js 18.0.0 以上が必要です。Node.js をはじめて使う場合はインストールする必要があります。

2. Qiita CLI をインストールする

Qiita のコンテンツを管理したいディレクトリで、以下のコマンドを実行します。

npm install @qiita/qiita-cli --save-dev

以下のコマンドでバージョンが表示されればインストール完了です。

npx qiita version

3. Qiita CLI をアップデートする

Qiita CLI をアップデートする場合は以下のコマンドを実行します。

npm install @qiita/qiita-cli@latest

Qiita CLI のセットアップ方法について

init コマンドを実行する

以下のコマンドを実行することで、

.gitignore
GitHub Actions のワークフローファイル
- 「GitHub で記事を管理する」の項目を参照
ユーザー設定ファイル（qiita.config.json）
- 「ユーザー設定ファイルについて」の項目を参照

が生成されます。

npx qiita init

Qiita のトークンを発行する

以下の流れでトークンを発行してください。

https://qiita.com/settings/tokens/new へログインした状態でアクセスします。
- トークンの権限には「read_qiita」と「write_qiita」を設定します。

発行したトークンはQiita CLIのログイン、GitHubで記事を管理するで利用します。

Qiita CLI のログイン

以下のコマンドより発行したトークンの登録を行います。

npx qiita login

発行したトークンを入力: トークンを入力しEnterキーを押す
Hi ユーザー名!

トークンを登録することで、Qiita のアカウントと紐付けがされ、記事の取得や投稿、更新が行えるようになります。

Qiita Preview の起動（プレビュー画面の表示）

本文の執筆は、ブラウザでプレビューしながら確認できます。ブラウザでプレビューするためには以下のコマンドを実行します。
コマンド実行時に、Qiita に投稿している記事がダウンロードされます。

npx qiita preview

コマンド実行すると、Qiita Preview(プレビュー画面)にアクセスすることが可能になります。
プレビュー画面のデフォルトの URL は http://localhost:8888 です。

記事ファイルの配置について

1 つの記事の内容は、1 つの markdown ファイル（◯◯.md）で管理します。
記事ファイルはpublicディレクトリ内に含める必要があります。

.
└─ public
   ├── newArticle001.md
   └── newArticle002.md

Qiita CLI で記事を管理する

記事の作成

Qiita Preview 上の「新規記事作成」ボタン、または以下のコマンドで新規記事を作成できます。

npx qiita new 記事のファイルのベース名

記事のファイルのベース名は自由に変更が可能です。

記事のファイル名をnewArticle001.mdにしたい場合はnewArticle001にします。

例): $ npx qiita new newArticle001

作成された記事ファイルの中身は次のようになっています。

---
title: newArticle001 # 記事のタイトル
tags:
  - "" # タグ（ブロックスタイルで複数タグを追加できます）
private: false # true: 限定共有記事 / false: 公開記事
updated_at: "" # 記事を投稿した際に自動的に記事の更新日時に変わります
id: null # 記事を投稿した際に自動的に記事のUUIDに変わります
organization_url_name: null # 関連付けるOrganizationのURL名
slide: false # true: スライドモードON / false: スライドモードOFF
---
# new article body

ファイルの上部には---に挟まれる形で記事の設定（Front Matter）が含まれています。
ここに記事のタイトル（title）やタグ(tags)などを yaml 形式で指定します。

記事の投稿・更新

Qiita Preview 上の「記事を投稿する」ボタン、または以下のコマンドで投稿・更新ができます。

npx qiita publish 記事のファイルのベース名

以下のコマンドで全ての記事を反映させることができます。

npx qiita publish --all

--forceオプションを用いることで、強制的に記事ファイルの内容を Qiita に反映させます。

npx qiita publish 記事ファイルのベース名 --force
# -f は --force のエイリアスとして使用できます。
npx qiita publish 記事ファイルのベース名 -f

記事の削除

Qiita CLI、Qiita Preview から記事の削除はできません。
publicディレクトリから markdown ファイルを削除しても Qiita 上では削除はされません。

Qiita上で記事の削除を行なえます。

GitHub で記事を管理する

Qiitaでは、Qiita CLIを使うことで、Qiitaの記事をGitHubリポジトリで管理できます。
Qiitaの記事をGitHubリポジトリで管理する方法については以下の記事をご覧ください。

Qiita CLI のコマンド、オプションについて

help

簡単なヘルプが見れます。

npx qiita help

pull

記事ファイルを Qiita と同期します。
Qiita 上で更新を行い、手元で変更を行っていない記事ファイルのみ同期されます。

npx qiita pull

--forceオプションを用いることで、強制的に Qiita 上の内容を記事ファイルに反映させます。

npx qiita pull --force
# -f は --force のエイリアスとして使用できます。
npx qiita pull -f

version

Qiita CLI のバージョンを確認できます。

npx qiita version

ユーザー設定ファイルについて

npx qiita initコマンドで生成されるqiita.config.jsonについて説明します。
このファイルを用いて、Qiita CLI の設定を行うことができます。
設定できるオプションは以下の通りです。

includePrivate: 限定共有記事を含めるかどうかを選べます。デフォルトはfalseです。
port: qiita previewコマンドで利用するポートを指定できます。デフォルトは8888です。

オプション

--credential <credential_dir>

Qiita CLI の認証情報（credentials.json）を配置する・しているディレクトリを指定できます。
デフォルトでは$XDG_CONFIG_HOME/qiita-cliもしくは$HOME/.config/qiita-cliになっています。

npx qiita login ---credential ./my_conf/
npx qiita preview --credential ./my_conf/

--config <config_dir>

Qiita CLI の設定情報（qiita.config.json）を配置する・しているディレクトリを指定できます。

デフォルトでは、カレントディレクトリになります。

例）

npx qiita login --config ./my_conf/
npx qiita preview --config ./my_conf/

--root <root_dir>

記事ファイルがダウンロードされるディレクトリを指定できます。
デフォルトでは、カレントディレクトリになります。

例）

npx qiita preview --root ./my_articles/
npx qiita publish c732657828b83976db47 --root ./my_articles/

--verbose

詳細なログを出力できます。

npx qiita login --verbose
npx qiita preview --verbose