Skip to content

Latest commit

 

History

History
322 lines (211 loc) · 12 KB

README.md

File metadata and controls

322 lines (211 loc) · 12 KB

Qiita CLI

Qiita CLI、Qiita Preview へようこそ!

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

ご利用の前に

Qiita CLI、Qiita Preview を利用されたら、利用規約プライバシーポリシーに同意したものとみなします。

こちらの記事リンクもご覧ください

⭐ スターのお願い

少しでも興味が湧いたり、実際に使用してみてQiita CLIが便利だと感じたら、ぜひGitHubリポジトリにスターをつけていただけると嬉しいです。 スターをいただけると、開発のモチベーションが上がり、さらに良いツールをみなさんにお届けする力になります。

📝 記事投稿のお願い

Qiita CLIを使って記事が書けたら、ぜひQiitaに投稿してみてください。 投稿された記事は、多くの人々に役立ち、知識が共有されることに繋がります。 どんな些細な内容でも大丈夫ですので、ぜひ気軽にご投稿ください🙇‍♂️

Qiita CLI関する記事

👉🏻 ご質問・フィードバックについて

より多くのフィードバックが集まることで、みなさんのお役に立てる機能をどんどん追加することができます。

  • よくあるお問い合わせ等を記載しております → FAQ
  • 不具合やご意見などございましたらQiita Discussionsへご投稿ください。

Qiita CLI の導入方法について

1. 事前準備

Qiita CLI を使うには Node.js 18.18.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 のトークンを発行する

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

発行したトークンは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
ignorePublish: false # true: `publish`コマンドにおいて無視されます(Qiitaに投稿されません) / false: `publish`コマンドで処理されます(Qiitaに投稿されます)
---
# 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 の設定について

以下の流れで設定を行うことで、GitHub の特定のブランチにコミットしたタイミングで記事の投稿や更新を行うことが可能になります。

  1. GitHub にリポジトリを作成します。
  2. https://github.com/[ユーザー名]/[リポジトリ名]/settings/secrets/actions から、シークレットにQIITA_TOKENという名前で発行した Qiita のトークンを保存します。
  3. qiita init を実行したディレクトリ全体を作成したリポジトリにプッシュします。

デフォルトはmainまたはmasterブランチにコミットがあった場合、自動で Qiita へ記事の投稿・更新がされます。
処理の実行の条件は.github/workflows/publish.ymlから変更することが可能です。

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: qiita.com からダウンロードして保存する記事に限定共有記事を含めるかどうかを選べます。デフォルトはfalseです。
  • host: qiita previewコマンドで利用するホストを指定できます。デフォルトはlocalhostです。
  • 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

FAQ

限定共有投稿をする方法がわからない

ユーザー設定ファイルで下記指定をします。
includePrivate: true (デフォルトはfalseです。)
qiita.com からダウンロードして保存する記事に限定共有記事を含めるかどうかを選べます。

記事ファイルで下記指定をします。
private: true(private: false # true: 限定共有記事 / false: 公開記事)

エラーが出て解決しない

現在、エラー内容が適切に表示できていない場合がございます。

エラーを解決できない場合は、こちらのDiscussions も参考にしてみてください🙇
increments/qiita-discussions#561

不具合・ご意見は Discussions へ

不具合・ご意見等ございましたらQiita Discussionsへお寄せください。