Qiita CLI とは、手元の環境で記事の執筆・プレビュー・投稿ができるツールです。 Qiita CLI を使うことで、普段お使いのエディタなどを使って記事の執筆・投稿がしやすくなります。
不具合やご意見などございましたらQiita Discussionsへご投稿ください。
Qiita CLI、Qiita Preview を利用されたら、利用規約、プライバシーポリシーに同意したものとみなします。
コミュニティガイドライン をご確認ください。 みんながより良い体験をするためのマナーについて書かれています。
また、記事を書く上で意識すると望ましいもの、気をつけるべき点を良い記事を書くためのガイドラインにまとめています。
Qiita の Markdown 記法についてはMarkdown 記法 チートシートをご覧ください。
Qiita CLI を使うには Node.js 18.0.0
以上が必要です。Node.js をはじめて使う場合はインストールする必要があります。
Qiita のコンテンツを管理したいディレクトリで、以下のコマンドを実行します。
npm install @qiita/qiita-cli --save-dev
以下のコマンドでバージョンが表示されればインストール完了です。
npx qiita version
Qiita CLI をアップデートする場合は以下のコマンドを実行します。
npm install @qiita/qiita-cli@latest
以下のコマンドを実行することで、
- .gitignore
- GitHub Actions のワークフローファイル
- 「GitHub で記事を管理する」の項目を参照
- ユーザー設定ファイル(qiita.config.json)
- 「ユーザー設定ファイルについて」の項目を参照
が生成されます。
npx qiita init
以下の流れでトークンを発行してください。
- https://qiita.com/settings/tokens/new へログインした状態でアクセスします。
- トークンの権限には「read_qiita」と「write_qiita」を設定します。
発行したトークンはQiita CLIのログイン
、GitHubで記事を管理する
で利用します。
以下のコマンドより発行したトークンの登録を行います。
npx qiita login
発行したトークンを入力: トークンを入力しEnterキーを押す
Hi ユーザー名!
トークンを登録することで、Qiita のアカウントと紐付けがされ、記事の取得や投稿、更新が行えるようになります。
本文の執筆は、ブラウザでプレビューしながら確認できます。ブラウザでプレビューするためには以下のコマンドを実行します。 コマンド実行時に、Qiita に投稿している記事がダウンロードされます。
npx qiita preview
コマンド実行すると、Qiita Preview(プレビュー画面)にアクセスすることが可能になります。 プレビュー画面のデフォルトの URL は http://localhost:8888 です。
1 つの記事の内容は、1 つの markdown ファイル(◯◯.md)で管理します。
記事ファイルはpublic
ディレクトリ内に含める必要があります。
.
└─ public
├── newArticle001.md
└── newArticle002.md
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 の特定のブランチにコミットしたタイミングで記事の投稿や更新を行うことが可能になります。
- GitHub にリポジトリを作成します。
- https://github.com/[ユーザー名]/[リポジトリ名]/settings/secrets/actions から、シークレットに
QIITA_TOKEN
という名前で発行した Qiita のトークンを保存します。 - qiita init を実行したディレクトリ全体を作成したリポジトリにプッシュします。
デフォルトはmain
またはmaster
ブランチにコミットがあった場合、自動で Qiita へ記事の投稿・更新がされます。
処理の実行の条件は.github/workflows/publish.yml
から変更することが可能です。
簡単なヘルプが見れます。
npx qiita help
記事ファイルを Qiita と同期します。 Qiita 上で更新を行い、手元で変更を行っていない記事ファイルのみ同期されます。
npx qiita pull
--force
オプションを用いることで、強制的に Qiita 上の内容を記事ファイルに反映させます。
npx qiita pull --force
# -f は --force のエイリアスとして使用できます。
npx qiita pull -f
Qiita CLI のバージョンを確認できます。
npx qiita version
npx qiita init
コマンドで生成されるqiita.config.json
について説明します。
このファイルを用いて、Qiita CLI の設定を行うことができます。
設定できるオプションは以下の通りです。
- includePrivate: 限定共有記事を含めるかどうかを選べます。デフォルトは
false
です。 - port:
qiita preview
コマンドで利用するポートを指定できます。デフォルトは8888
です。
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/
Qiita CLI の設定情報(qiita.config.json
)を配置する・しているディレクトリを指定できます。
デフォルトでは、カレントディレクトリになります。
例)
npx qiita login --config ./my_conf/
npx qiita preview --config ./my_conf/
記事ファイルがダウンロードされるディレクトリを指定できます。 デフォルトでは、カレントディレクトリになります。
例)
npx qiita preview --root ./my_articles/
npx qiita publish c732657828b83976db47 --root ./my_articles/
詳細なログを出力できます。
npx qiita login --verbose
npx qiita preview --verbose