Qiita CLI を mise と pnpm で導入して GitHub 連携で Qiita に記事を投稿しよう！

![ロゴ mise pnpm qiita](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3869171/aae9f48f-8787-4316-aae6-8e963f7d7da3.png)

## はじめに

現在 2025 年 4 月。
Qiita CLI がリリースされて約2年、 Node.js を取り巻く環境も激変しています。この記事では界隈で最新のツール mise-en-place と pnpm を使って Qiita CLI が導入できたので紹介します。

そろそろ大型連休、この機会に最新ツールで Qiita CLI を導入して記事をアウトプットしてみませんか?

## 記事について

目的は下記2つです。少しボリュームがあるので画面右の目次を活用するなどして必要な部分をお読みください。

- [Qiita CLI の導入](#qiita-cli-の導入)
  Qiita CLI を mise-en-place と pnpm で新規に Qiita CLI を導入します。インストール済み環境の移行には触れません。

- [記事管理の運用を理解](#記事管理の運用)
  公式記事で私がわからなかったことを積み増しました。また VSCode, Git などのツールについても初心者 (自分のこと:sweat_drops:) 向けにざっくり説明しています。

初心者の初心者による初心者向けの記事ですので、間違いやわかりにくい点、他にも知っておくと良い話などあれば教えてください。コメント、Xなどでも大歓迎です:bow::

---

慣れてきたり、手早く読みたいときにはシンプル版をどうぞ。

https://qiita.com/AMASAShiro/items/35bf120c868d5646fe06

https://qiita.com/AMASAShiro/items/5f37430f14536bc17b49

## 動作確認環境

以下の環境で導入しました。

- MacBook Air Retina, 13-inch, 2018 Intel
- MacOS Sonoma 14.7.5

本稿ではコマンド・ファイル配置などは macOS を前提に説明しています。
なおすべての挙動を確認したわけではありません。[^1]

## 想定読者

- Mac 初心者。コマンドラインは少し使える
- Homebrew, VSCode, git, GitHub を少し使える (インストール・設定は済んでる)
- 新しいツールで開発環境構築してみたい
- これから Qiita で記事を公開したい
- 記事を GitHub で管理したい
- Qiita CLI の記事は読んだけどむずかしい…:confounded:

## ツール紹介

### mise-en-place

https://mise.jdx.dev/

> mise は多言語対応ツールのバージョン管理ツールです。 asdf、nvm、pyenv、rbenv などのツールの代替となります。

と公式サイトの紹介はあっさりめ。付け加えると、カレントディレクトリに基づいてツールのバージョンや環境変数を自動的に切り替える [direnv](https://direnv.net/) 的な機能や、タスクランナーの機能もあります。  また asdf や rtx の後継らしく[非常に多くのツール](https://mise.jdx.dev/registry.html)を使うことができます。
言語は Bun, Deno, Elixir, Erlang, Go, Java, NodeJS, Python, Ruby, Rust, Swift, Zig が[コアツール](https://mise.jdx.dev/core-tools.html)でサポートされています。

対応OSは macOS, Linux, Windows。[公式のインストール方法の説明](https://mise.jdx.dev/getting-started.html)が充実していてインストールは簡単です。

便利だなって思ったのは以下の点。

- 多様な言語環境の実行環境のバージョンをこれ 1 つで管理できる
- コマンド 1 つで実行環境のインストールと direnv 的な機能が使える
- 実行環境のインストール先が一元化されており管理が楽  

なお、mise en place はフランス語で意味は「料理の準備、下ごしらえ」、読み方は「ミーゾンプラス」[^2]です。以降 mise 「ミーズ」と呼びます。

### pnpm

https://pnpm.io/ja/

> 高速、かつディスク容量効率が良いパッケージマネージャー

こちらもあっさり。Node.js の npm の改良版だそうです。特徴は以下。

- 速い : npm に比べて 2 倍以上
- 効率的 : node_modules のファイルは一元管理。プロジェクトではそこへのハードリンク
- モノレポサポート
- 厳格

使ってみたところ確かに速い！npm と比較すると体感 2 倍どころではありません。  
またパッケージが一元管理っていうのもディスク容量に優しくて素敵。プロジェクトフォルダをコピーしても同一ボリュームならディスク容量が気にならないの、いいですよね。 [^3]

対応OSは macOS, Linux, Windows。こちらも[公式のインストール方法の説明](https://pnpm.io/ja/installation)が充実していてインストールは簡単です。

## Qiita CLI の導入

Qiita CLI 公式記事は以下の3つ。情報が分散して分かりづらかったのでこの記事でまとめて説明します。

https://github.com/increments/qiita-cli

https://qiita.com/Qiita/items/666e190490d0af90a92b

https://qiita.com/Qiita/items/32c79014509987541130

### Qiita CLI とは

Qiita に記事を投稿するには [Qiita にアクセス](https://qiita.com/)し、ブラウザで Web エディタを使うことが一般的です。でも執筆には普段使い慣れた PC のエディタを使いたいですよね？投稿もできるだけ簡単に。これを実現するのが Qiita CLI です。

Qiita CLI は TypeScript で書かれたプログラムで Node.js 環境で動きます。またインターネット接続が必要です。

### Qiita CLI の機能

Qiita CLI は記事の **作成**  、**プレビュー** 、 **投稿** 、**取得** 機能を提供します。  

- **記事の作成**  
  ローカル PC の所定のフォルダに新規記事のファイルを作成します。このファイルにはタイトル情報や投稿時の記事の扱い方の指示などを含む[フロントマター](#フロントマターの指定)があります。

- **記事のプレビュー**  
  ローカル PC で管理している記事の一覧から記事をプレビューします。
  コマンドを実行すると、ローカル PC で Web サーバー とブラウザを起動し PC 内の記事一覧が表示されるので、記事を選択してプレビューします。  

- **記事の投稿**  
  投稿のコマンドを実行、または GitHub に記事を反映することで Qiita に記事を投稿します。[管理方式](#管理方式)により方法が違います。

- **記事の取得**  
  ローカル PC の記事より新しい Qiita の記事をローカル PC に取得します。

### 運用設計

Qiita CLI の導入・運用前に管理方式、フォルダ、リポジトリについて 3 点を検討し、決定します。

#### 管理方式

Qiita CLI を使った記事管理の運用には次の2通りがあります。どちらで運用するか決めておきます。

1. **ローカル運用**
   自分の PC (以降ローカル PC)だけで記事を管理。手軽。バックアップは別途自分で。
2. <font color="red">**GitHub 運用**</font>
   GitHub で記事を管理すると GitHub 上のリモートリポジトリに記事を反映すると Qiita に記事を投稿できます。本稿ではこの運用をメインに説明します。

:::note warn
<font color="red">**GitHub 運用**</font>でも Qiita の管理画面から記事を変更できます。ただしこの場合 Qiita の記事と GitHub やローカル PC の記事ファイルで差分が発生するので、記事を取得するコマンドを使う、また記事を編集するなど手動で差分を解消する作業が必要です。[^4]
:::

#### フォルダ設計

ローカル PCで記事ファイルを管理する**記事フォルダ**を決めます。

  例) `~/Documents/publish/qiita`

また Qiita で削除した記事を管理する**削除記事フォルダ**を決めます。

  例) `~/Documents/publish/qiita/deleted`

:::note info
**削除記事フォルダ**は削除済みの記事を保管する場所です。記事削除では所定の記事配置フォルダ `記事フォルダ/public` から記事ファイルを削除する必要があるため、削除記事を保管したい場合に使用します。[^5]
:::

#### リポジトリ設計・作成

<font color="red">**GitHub 運用**</font>の場合 GitHub 上の**記事リモートリポジトリ**について決め、[GitHub にログイン](https://github.com/)してリポジトリを作成しておきます。

- **記事リモートリポジトリ**  
  記事ファイルを管理する GitHub 上のリポジトリです。以下は例です。
  - **リポジトリ名** : qiita
  - デフォルトブランチ : main
  - **公開範囲** : Private
  - Add a README file : なし
  - Add .gitignore : None
  - Choose a license : None

:::note info
リポジトリ名はローカル PC での記事フォルダと同じ名前にすると、このあとのクローンでそのまま**記事フォルダ**として使えます。
デフォルトブランチは main にします。 Qiita CLI は main または master ブランチの変更を検知し Qiita に記事を投稿します。
公開範囲は Private 、 Public どちらも使えます。
:::

## Qiita CLI 導入準備

下記 3 点を実施します。

1. **記事フォルダ**の作成
2. **Qiita アクセストークン**の作成
3. GitHub への **Qiita アクセストークン**の登録 (<font color="red">**GitHub 運用**</font>時のみ)

### 記事フォルダの作成

**ローカル運用**の場合、**記事フォルダ**、**削除記事フォルダ**を作成します。

```zsh: ローカル運用: フォルダの作成
mkdir -p ~/Documents/publish/qiita # -p: フォルダをサブフォルダごと作成
mkdir -p ~/Documents/publish/qiita/deleted
```

<font color="red">**GitHub 運用**</font>の場合、GitHub の**記事リモートリポジトリ**をクローンします。また**削除記事フォルダ**を作成します。

```zsh:GitHub 運用: クローンでのフォルダの作成
mkdir ~/Documents/publish # 記事フォルダの親フォルダを作成
cd ~/Documents/publish
git clone 記事リモートリポジトリの url
```

```zsh:GitHub 運用: 削除記事フォルダを作成、追跡対象から除外
mkdir -p ~/Documents/publish/qiita/deleted
echo deleted >> .gitignore
```

:::note info
VSCode でもクローンできます。指定したフォルダに GitHub 上のリポジトリ名のフォルダが作成されます。
![VSCode でクローン](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3869171/7fe752e2-abcc-4c8a-a6dc-5138576e47bf.png)
:::

### Qiita アクセストークンの作成

Qiita CLI で Qiita にアクセスするため Qiita が発行する **Qiita アクセストークン**を作成します。

:::note warn
Qiita CLI では ID ・パスワードは使用しません。この **Qiita アクセストークン**がクレデンシャル情報です。人に知られないよう機密性に注意して管理します。
:::

:::note info
セットアップ時に[Qiita 認証情報設定](#qiita-認証情報設定)、また<font color="red">**GitHub 運用**</font>では[GitHub への Qiita アクセストークンの登録](#github-への-qiita-アクセストークンの登録) でも使用します。運用中に意識することはありません。
:::

[Qiita にログイン](https://qiita.com/)し、メニューから【設定】→【アプリケーション】→【個人用アクセストークン】にある【新しくトークンを発行する】をクリックします。

表示された画面で以下の内容を入力して【発行する】をクリックします。

- アクセストークンの説明 : なんでも良い 例) github_qiita
- スコープ : **read_qiita**, **write_qiita** にチェック

**Qiita アクセストークン**が表示されるのでクリップボードにコピーします。

![Qiita アクセストークン発行](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3869171/ea8eb179-99a4-4213-9393-8824dc06e552.png)

:::note alert
**Qiita アクセストークンは発行時のみ表示されます。あとから確認できません。**
:::

### GitHub への Qiita アクセストークンの登録

<font color="red">**GitHub 運用**</font>の場合、GitHub に **Qiita アクセストークン**を登録します。**ローカル運用**ではこの手順は不要です。

[GitHub にログイン](https://github.com/)して**記事リモートリポジトリ**を表示し、【Settings】→【Security / Secrets and variables】→【Actions】で表示される画面で【New repository secret】をクリックします。

![GitHub secret 設定画面](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3869171/d11b54bb-93d2-4815-9141-5fb9af96eccf.png)

表示された画面で以下の内容を入力して【Add secret】をクリックします。

- Name : **QIITA_TOKEN**
- Secret : 発行された **Qiita アクセストークン**

:::note warn
Secret の名前は必ず **QIITA_TOKEN** にします。
:::

## Qiita CLI のセットアップ

### 使用ツール

Qiita CLI を使うにあたり、ここでは下記ツールを使います。(動作確認時のバージョン)

- **[mise](https://mise.jdx.dev/)** (2025.4.4 macos-x64 (2025-04-15))
- **[Node.js](https://nodejs.org/ja)** (23.11.0)
- **[pnpm](https://pnpm.io/ja)** (10.8.0)
- **[Qiita CLI](https://github.com/increments/qiita-cli)** (1.6.2)
  
- **[Visual Studio Code](https://code.visualstudio.com/)** (1.99.2)
- パッケージマネージャー
  - macOS : **[Homebrew](https://brew.sh/ja/)** (4.4.31)
  - Windows : **[winget](https://learn.microsoft.com/ja-jp/windows/package-manager/winget/)**  
  など

<font color="red">**GitHub 運用**</font>では下記ツールを使用します。

- **[Git](https://git-scm.com/)** (2.49.0)

### セットアップ手順

インストール・設定の流れは以下です。

1. mise インストール
2. Node.js / pnpm インストール
3. Qiita CLI インストール
4. 記事フォルダを GitHub リポジトリに反映  (<font color="red">**GitHub 運用**</font>時のみ)
5. Qiita 認証情報設定 (Qiita CLI のログイン)
6. 動作確認

### mise インストール

```zsh:Mac での mise インストールとアクティベーション
brew install mise
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
source ~/.zshrc
```

```zsh:mise 動作確認
mise --version
# 実行結果例
              _                                        __              
   ____ ___  (_)_______        ___  ____        ____  / /___ _________
  / __ `__ \/ / ___/ _ \______/ _ \/ __ \______/ __ \/ / __ `/ ___/ _ \
 / / / / / / (__  )  __/_____/  __/ / / /_____/ /_/ / / /_/ / /__/  __/
/_/ /_/ /_/_/____/\___/      \___/_/ /_/     / .___/_/\__,_/\___/\___/
                                            /_/                 by @jdx
2025.4.4 macos-x64 (2025-04-15)
```

:::note info
VSCode に [mise を統合する拡張機能](https://mise.jdx.dev/ide-integration.html#vscode)があります。必要に応じて導入します。[^6]
:::

### Node.js / pnpm インストール

Node.js と npm の代わりに使う pnpm を mise でインストールします。

インストールはプロジェクト単位とするので、カレントディレクトリを**記事フォルダ**にして作業します。[^7][^8]

```zsh: pnpm インストール
cd ~/Documents/publish/qiita # 記事フォルダに移動
mise use node@latest
mise use pnpm@latest
pnpm init
```

### Qiita CLI インストール

Qiita CLI をインストールし初期化します。カレントディレクトリは**記事フォルダ**のままです。

```zsh: Qiita CLI インストール
pnpm install @qiita/qiita-cli
pnpm qiita init # 初期化。pnpxではエラーになった
pnpm qiita version
```

### 記事フォルダを記事リモートリポジトリに反映

<font color="red">**GitHub 運用**</font>の場合 GitHub 上の**記事リモートリポジトリ**に初期化済みの**記事フォルダ**を反映します。**ローカル運用**ではこの手順は不要です。

```zsh:GitHub 運用 : GitHub にプッシュ
git add *
git commit -m "Initial Commit"
git push -u origin main
```

:::note info
VSCode を使用している場合は上記コマンドを使わなくても、エディタ画面の左にある【ソース管理】ボタンを押し、【変更】に `Initial Commit` と入力、コミットボタン右の【v】をクリックして【コミットしてプッシュ】ボタンをクリックすることで同じことができます。

![VSCode でコミットしてプッシュ](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3869171/ed857237-8474-43dc-8e73-2ee2bf2c624d.png)
:::

:::note warn
この段階で GitHub Actions の処理結果を確認するとエラーがあるかもしれませんが問題ありません。これはまだ GitHub 上に記事管理用のディレクトリ `public` がないために発生しています。このあと記事の作成コマンドで自動的に作成されます。

![GitHub Actions 初回実行時エラー](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3869171/ebb86133-7b47-4c88-b188-3be95e96fd32.png)
:::

### Qiita 認証情報設定

Qiita の認証情報である **Qiita アクセストークン**をローカル PC に設定します。
下記コマンドを実行するとプロンプトが表示されるので **Qiita アクセストークン**を入力します。

```: Qiita 認証情報設定
pnpm qiita login

以下のURLにアクセスしてトークンを発行してください。（「read_qiita」と「write_qiita」にチェックを入れてください）
  https://qiita.com/settings/tokens/new?read_qiita=1&write_qiita=1&description=qiita-cli
  
発行したトークンを入力: 
```

:::note info
[Qiita CLI 導入の公式記事](https://qiita.com/Qiita/items/666e190490d0af90a92b#qiita-cli-%E3%81%AE%E3%83%AD%E3%82%B0%E3%82%A4%E3%83%B3)では 「Qiita CLI のログイン」と呼ばれています。[^9]
:::

### Qiita CLI の設定

設定ファイル `記事フォルダ/qiita.config.json` を変更します。

- 限定共有する場合[^10]  
  `"includePrivate" : false`  
  false を **true** に変更

- Qiita CLI プレビュー機能のポートが重複する場合  
  `"port" : 8888`  
  8888 を**重複しないポート番号**に変更

```json: 変更後の qiita.config.json 例
{
  "includePrivate": true,
  "host": "localhost",
  "port": 8888
}
```

### 補足 - Qiita CLI のアップデート

Qiita CLI がバージョンアップされた時は Qiita CLI をアップデートします。

```zsh: Qiita CLI アップデートコマンド
pnpm update @qiita/qiita-cli --latest
```

## 記事管理の運用

記事管理は以下の流れで実施します。

- 執筆準備 : 記事一覧、記事を確認する管理画面を起動するため、記事の一覧確認コマンドを実行

- 通常作業
  1. 記事の作成 : 新規に記事ファイルを作成
  2. 記事の執筆 : 記事を執筆します。(ここでは執筆に必要な情報を説明)
  3. 記事の確認 : 投稿前に管理画面から記事を確認
  4. 記事の投稿 : 記事を投稿

- 個別作業
  - 記事の削除 : Qiita サイト上の記事を削除
  - 記事の取得 : Qiita サイト上の記事を取得
    - Qiita CLI 運用前に既存記事を取り込む
    - Qiita サイトでの記事を変更した場合

### 記事の一覧確認

**記事フォルダ**で下記コマンドを実行します。するとブラウザが起動し、記事管理画面が表示されます。  

```zsh:記事の一覧確認コマンド
cd ~/Documents/publish/qiita  # 記事フォルダに移動
pnpm qiita preview &
```

![[Qiita CLI プレビュー]](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3869171/8cbde73d-a43a-4e5b-b8a5-1f5f22624795.png)

ローカル PC の記事の一覧や記事の見栄えを確認したり、記事の画像をアップロードするにはこの画面から実施します。

:::note info
コマンドを実行するとローカル PC で Web サーバーが起動されます。非同期なのでコマンドを実行したターミナルでは Web サーバーを終了するまで他の操作ができません。なのでバックグラウンドで実行するために `&` をつけて実行します。
:::

:::note warn
VSCode を使う場合、以下 2 点により`preview` コマンドは VSCode 以外のターミナルを使うほうがいいでしょう。

- VSCode を終了するとプレビュー用の Web サーバーが終了し、管理画面を確認できません。よく VSCode を再起動するケースでは特に面倒です。
- コマンドを実行したターミナルではエラー・ワーニングのメッセージが出力されることがあります。[^11]
:::

:::note alert
Qiita CLI のプレビュー機能は起動時だけでなく作業時にもインターネット接続が必要です。インターネット接続が失われるとプレビュー機能はエラーを出力して終了します。
:::

:::note info
作業が終わってプレビュー機能を終了するには次のようにします。
```zsh: バックグラウンドジョブを終了する
# バックグラウンドジョブを確認する
jobs
[1]  + running    pnpm qiita preview
# バックグラウンドジョブを終了する
kill %ジョブ番号 # kill %1 で終了
```

:::

### 記事の作成

**記事フォルダ**で下記コマンドを実行します。するとローカル PC に新規記事ファイルが作成されます。このファイルは Qiita CLI に記事の扱い方を指示する[フロントマター](#フロントマターの指定)を含みます。

```zsh:記事の新規作成コマンド
pnpm qiita new 記事のベース名
```

:::note info
記事のベース名はファイル名の拡張子を含めません。ファイル名には自動的に`.md`がつきます。  
:::

#### 記事フォルダの構成

記事フォルダの構成は以下のとおりです。  

```:記事フォルダの構成
記事フォルダ
└─ public
   ├── .remote/
   ├── article-1.md
   ├── :
   └── article-n.md
```

:::note info
新規記事作成時に `public` フォルダがない場合、コマンド実行時に作成されます。
`.remote/` フォルダは記事取得コマンド `pnpm qiita pull` が使います。
:::

### 記事の執筆

記事の執筆で必要な情報下記 3 点について説明します。

- フロントマターの指定
- Qiita Markdown の知識
- 画像の扱い

#### フロントマターの指定

記事ファイルには記事の情報・扱い方を指定するフロントマターがあります。

```yaml: 新規作成した記事のフロントマター
---
title: 記事のベース名
tags:
  - ''
private: false
updated_at: ''
id: null
organization_url_name: null
slide: false
ignorePublish: false
---
# new article body
```

- 指定する項目
  - title : **Qiita での記事タイトル**。\<h1\>扱い
  - tags : 1タグ1行。**最低1個は必要**。**最大5個**
  - private : false : 公開 | true : 限定共有
  - organization_url_name : 関連付ける Organization の url 名
  - slide : false : スライドモード オフ | true : オン
  - ignorePublish : false : 投稿する | true : 投稿しない

:::note warn
公開前に `title` 、`tags` は必ず指定します。
`title` は Qiita で公開したときに記事のタイトルになります。Qiita 上では \<h1\> になります。なので記事ファイルでは見出しは `##` で始めます。[^12]
:::

:::note warn
`updated_at` (記事の更新日時)、 `id` (記事の UUID) は Qiita CLI の制御用情報です。Qiita CLI コマンドが自動的に更新します。手動では変更しません。
:::

:::note info
限定共有記事を公開記事にするには `private: false` を `true` に変更して投稿します。
:::

:::note alert
公開記事を限定共有記事にはできません。
:::

#### Qiita Markdown の知識

- Qiita Markdown について学んでおくと効率的に記事を執筆できます。[^13]

https://qiita.com/Qiita/items/c686397e4a0f4f11683d

- 記事ファイルの改行はそのまま Qiita の記事に反映されます。[^14]

- 文字に色を付けるには html タグの font で color を指定します。
  
  例) 文字に<font color="red">**色**を付けて</font>みる。

```html: 上記の html
例) 文字に<font color="red">**色**を付けて</font>みる。
````

- 内部リンクには以下の注意が必要のようです。

https://qiita.com/hennin/items/7ee58dd7d7c013a23be7

#### 画像の扱い

画像を記事に表示して確認するためには、あらかじめ画像を公開し、画像の url を記事に反映する必要があります。
ここでは Qiita での画像公開について説明します。

##### Qiita での画像アップロード

Qiita の画像アップロード機能で画像を公開できます。[Qiita CLI のプレビュー画面](#記事の確認)のメニューに Qiita のアップロード機能へのリンクがあります。
アップロードすると画像の url が入手できるので、記事に反映します。

:::note info
Qiita の画像アップロードでは一度に最大 5 ファイルをアップロードできます。このときアップロードした画像の url をまとめてコピーできます。まとめてコピーはアップロード画面でのみできます。
:::

##### Qiita での画像の削除  

Qiita の管理画面の【設定】→【アップロードしたファイル】の画面で画像ファイルを削除します。

:::note info
**ローカル運用**、<font color="red">**GitHub 運用**</font>のどちらでも画像の扱いは同じです。[^15]
:::

##### Qiita での画像の変更

変更したい画像を Qiita にアップロードし、記事の画像リンクを変更します。また不要になった画像を Qiita で削除します。

:::note alert
公開した画像を変更することはできません。
:::

##### 補足: 画像の扱い詳細

###### Qiita で表示される画像の幅

Qiita の本文で表示される画像の最大幅は PC では 708 px です。クリックすると拡大されるので画像をそのまま使うかクリッピングするかは適宜使いわけます。なお Qiita での画像アップロード上限は[画像のアップロード・削除方法 | Qiita ヘルプ](https://help.qiita.com/ja/articles/qiita-image-upload)にある通りです。

> 月に合計100MBまで、単体で10MBまでの画像ファイルをアップロードすることが可能です。

また画像には枠がつきます。[^16]

###### VSCode での画像ファイルの扱い

VSCode では Markdown ファイルに画像をドラッグアンドドロップして画像リンクの挿入と、**記事フォルダ**への画像ファイルのコピーができます。

Macでの操作 : Finder などで画像ファイルをドラッグし、 VCode 上でリンクを挿入したいテキストで⇧ (Shift) を押しながらドロップ

画像ファイルをコピーするフォルダは設定できます。以下は `記事フォルダ/assets` に記事毎のフォルダに画像ファイルを管理する設定例です。

```:画像ファイルを管理する記事フォルダ構成例
記事フォルダ
├─ public
│  ├── article-1.md
│  ├── :
│  └── article-n.md
└─ assets
   ├── article-1
   │   ├── image-1.png
   │   ├── :
   │   └── image-n.png
   ├── :
   └── article-n
       ├── image-1.md
       ├── :
       └── image-n.md
```

![VSCode の設定: 画像ファイルコピー先フォルダ設定](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3869171/da461eb4-a361-460e-a112-0780a4d715e9.png)

設定ファイルでは `markdown.copyFiles.destination` の部分です。設定の順序を変更する場合は設定ファイルで変更します。

```json: settings.json の設定部分
    "markdown.copyFiles.destination": {
        "public/**/*": "../assets/${documentBaseName}/",
        "/**/*": "/resources/",
    },
```

###### Mac でのスクリーンショット撮影

忘れがちなのでメモしておきます。

- Mac でのスクリーンショットの撮影
  - ⇧ ⌘ 3 (Shift + Command + 3) : フルスクリーン
  - ⇧ ⌘ 4 (Shift + Command + 4) : 矩形選択
  - ⇧ ⌘ 4 (Shift + Command + 4) を押して離した後スペースキー : ウィンドウ選択

矩形選択・ウィンドウ選択では画像に影がつきます。影無しで撮影するには ⌥ (Option) を押しながら撮影します。

Retina ディスプレイなどで画像サイズの縦横ピクセル数が倍になあるときは、プレビューアプリで【ツール】→【サイズ変更】で調整します。

### 記事の確認

まだ[記事の一覧確認のコマンド](#記事の一覧確認)を実行していない場合は、コマンドを実行します。

```zsh: 記事の一覧確認コマンド
cd ~/Documents/publish/qiita  # 記事フォルダに移動
pnpm qiita preview &
```

ブラウザの Qiita CLI プレュー画面の左メニューにある `Articles` から記事一覧を表示し、確認したい記事のファイルを選択してブラウザに表示します。

:::note info
投稿前の記事の確認方法は3通りあります。

1. Qiita CLI : Qiita CLI のプレビュー画面
2. VSCode 拡張 Qiita Markdown Preview : VSCode 上でプレビューを確認
3. Qiita : Qiita の Web エディタ

投稿後の画面に一番近いのは "3. Qiita" の Web エディタのプレビューです。投稿前に Web エディタに記事をカットアンドペーストして確認します。なお記事は自動的に下書きに保存されるので、確認作業作業完了後に下書きを削除します。
:::

### 記事の投稿

記事を投稿する方法は管理方法により異なります。

#### **ローカル運用**での投稿

**ローカル運用**の場合、投稿するには Qiita CLI の投稿用コマンドを実行します。コマンドを実行すると記事が投稿され、ローカル PC にある投稿した記事ファイルの[フロントマター](#フロントマターの指定)が更新されます。

**記事フォルダ**で下記コマンドを実行します。

```zsh:ローカル運用: 個別記事投稿コマンド
pnpm qiita publish 記事のベース名
```

複数の記事を投稿するには**記事フォルダ**で下記コマンドを実行します。

```zsh:ローカル運用: 全記事投稿コマンド
pnpm qiita publish --all
```

なんらかの理由で強制的に記事ファイルを投稿するには**記事フォルダ**で下記コマンドを実行します。

```zsh:ローカル運用: 強制投稿コマンド
pnpm qiita publish --force
```

#### <font color="red">**GitHub 運用**</font>での投稿

<font color="red">**GitHub 運用**</font>の場合、投稿するには GitHub の **記事リモートリポジトリ**の main ブランチに記事を反映します。コマンドを実行すると GitHub にある **記事リモートリポジトリ**の記事ファイルの[フロントマター](#フロントマターの指定)が更新されます。

```zsh: GitHub 運用: コミットでローカル PC の main ブランチに反映する例
git add public/article-1.md
git commit -m "記事公開: article-1"
```

```zsh: GitHub 運用: ローカル PC の main ブランチを push する例
git pull origin main
git push -u origin main
# GitHub Actions の動作完了まで待つ 
git pull origin main
```

:::note info
push 後に pull するのは、 push により GitHub Actions で投稿時に更新された**記事リモートリポジトリ**のファイルをローカル PC に反映するためです。
状況にもよりますがこの GitHub Actions の処理は時間がかかる (20 秒以上) ので、GitHub で Actions の処理完了を確認してから実施します。[^17]
:::

:::note warn
2 つめの pull し忘れると次の投稿時に次のようなエラーが出ることがあります。

```zsh:投稿時にエラー
hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
hint:
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
fatal: Need to specify how to reconcile divergent branches.
```

以下のコマンドで git のデフォルトマージ戦略を指定し、再度投稿のコマンドを実行します。

```zsh: git のデフォルトマージ戦略 設定例
git config --global pull.rebase false
```

それでもエラーが出る場合は競合の原因を特定し、手動で競合を解消します。
:::

:::note info
VSCode で**記事リモートリポジトリ**に反映することもできます。

1. 左の【ソース管理】ボタンを押す
2. コミットメッセージを入力する
3. 【コミット】ボタン右の【v】を押し、【コミットして同期】を選択する
4. GitHub Actions の処理完了を待つ。
5. main ブランチと**記事リモートリポジトリ**を同期する。

![VSCode で GitHub に記事反映](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3869171/3d15d497-9e9b-4333-8f94-67408da8aca6.png)
:::

:::note info
ブランチをわけている場合、 main ブランチの変更を反映します。

```zsh: main ブランチ変更のマージ例
switch ブランチ名
git merge origin main
```

:::

### 記事の削除

Qiita CLI 使用時は次の 2 手順で記事を削除します。

1. Qiita で記事を削除
2. 記事管理場所から記事を削除

:::note alert
Qiita から記事を削除したら記事管理場所 (**記事フォルダ**または GitHub の**記事リモートリポジトリ**) からも削除しないと、次回投稿時にエラーが発生します。
:::

#### 手順1: Qiita で記事を削除

[**Qiita**](https://qiita.com/) で記事を削除します。

- 公開記事: Qiita 【マイページ】から削除
- 限定共有記事: Qiita 【限定共有記事】から削除

:::note warn
Qiita CLI には記事の削除機能はありません。
:::

#### 手順2: 記事管理場所から記事を削除

Qiita から記事を削除したら管理方法により以下を実施します。

- **ローカル運用**
  **記事フォルダ**にある削除記事を削除します。または**削除記事フォルダ**に移動します。

- <font color="red">**GitHub 運用**</font>
  GitHub 上の**記事リモートリポジトリ**から削除記事を削除します。

```zsh:削除記事を管理対象から除外し GitHub に反映する例
git rm --cached article-1.md # さくっとファイルを削除するなら --cached は不要
git push origin main
# GitHub Actions の動作完了まで待つ 
git pull origin main
```

最後にローカル PC のファイルを削除します。または**記事削除フォルダ**に移動します。

### 記事の取得

Qiita に既存記事がある、Qiita の Web エディタで記事を操作したなどのときには、ローカル PC に記事を取得するため以下のコマンドを実行します。

```zsh: 記事の取得コマンド
pnpm qiita pull
```

何らかの理由で Qiita 上の記事を強制的に取得するには以下のコマンドを実行します。

```zsh: 記事の強制取得コマンド
pnpm qiita pull --force
```

記事を取得すると `public` フォルダに `UUID記事.md` という名前で記事ファイルができるので、わかりやすいファイル名に変更します。

:::note info
記事の取得コマンドを実行すると成功したと表示されるが `public` フォルダのファイルが更新されないときがあります。
このときファイル `public/.remote/記事UUID.md` が、取得コマンドを実行した更新時刻で存在すれば記事を取得できています。 `public` にあるファイルに手動で反映させます。
:::

<font color="red">**GitHub 運用**</font>の場合、取得した記事を GitHub の**記事リポジトリ**に反映します。

```zsh: GitHub 運用: 取得記事の GitHub への反映
git add public/article-1.md
git commit -m "pullした記事の反映"
git pull origin main
git push origin main
# GitHub Actions の動作完了まで待つ 
git pull origin main
```

## その他

### Qiita CLI 設定ファイル

- クレデンシャル情報 : `~/.config/qiita-cli/credentials.json`
- Qiita CLI 設定 : `記事フォルダ/qiita.config.json`

### Qiita CLI コマンド

```zsh: Qiita CLI コマンド一覧
pnpm qiita init
pnpm qiita login
pnpm qiita new 記事ベース名
pnpm qiita preview &
pnpm qiita publish 記事ベース名
pnpm qiita publish 記事ベース名 --force
pnpm qiita publish --all
pnpm qiita pull
pnpm qiita pull --force
pnpm qiita version
pnpm qiita help
```

```zsh: Qiita CLI オプション
--credential <credential_dir> : クレデンシャル情報ファイルの配置ディレクトリ指定
--config <config_dir> : Qiita CLI 設定ファイルの配置ディレクトリ指定
--root <root_dir> : 記事ファイルの配置ディレクトリ指定
--verbose : 詳細ログ出力
```

### 限定共有記事公開で動作確認

Qiita CLI のセットアップ後に実際に限定共有記事を投稿できるかを確認をするときの手順です。

- 記事を新規作成

```zsh: 新規記事作成コマンド
cd ~/Documents/publish/qiita
pnpm qiita new test-after-setup
```

- 記事ファイル修正

```markdown: テスト用限定共有記事ファイル test-after-setup.md
---
title: テスト用限定共有記事ファイル
tags:
  - 'テスト'
private: true
updated_at: ''
id: null
organization_url_name: null
slide: false
ignorePublish: false
---
## 限定共有で記事を投稿するテスト記事

この記事は限定共有で記事を投稿するテスト記事です。
ちゃんと投稿できればセットアップは確実に完了しています。

[Qiita](https://qiita.com/) でどう見えるか確認しよう
```

- 記事の投稿
  - VScode で記事を**記事リモートリポジトリ**に反映。その後 VSCode で同期

- 確認
  - ブラウザで [Qiita](https://qiita.com) を確認
  - VSCode でフロントマターの update_at 、 id が変更されているかを確認

- テスト記事の削除
  - Qiita で【限定共有記事】から記事を削除
  - VSCode で記事を削除し、GitHub に反映 (プッシュ)

## 謝辞

Qiita には、技術を共有できる素晴らしいサービスの提供、また Qiita CLI のような便利なツール提供に感謝します。
また Qiita CLI の公式ドキュメントは言うに及ばず、様々な技術情報の記事に助けられました。執筆、公開されている方々にも深く感謝します。

## 参考文献

### Qiita CLI

https://github.com/increments/qiita-cli

https://qiita.com/Qiita/items/666e190490d0af90a92b

https://help.qiita.com/ja/articles/qiita-article-guideline

https://help.qiita.com/ja/categories/qiita/usage/

https://qiita.com/Qiita/items/c686397e4a0f4f11683d

https://qiita.com/Qiita/items/e84f5aad7757afce82ba

https://help.qiita.com/ja/articles/qiita-image-upload

### ツール類

https://mise.jdx.dev/

https://pnpm.io/ja/

## 最後に

Qiita CLI は便利でいいですね。でも私のような git とか GitHub は使ったことがないし、Node.js や npm ってなに？っていうくらいの初心者には公式ドキュメントを読んでも運用方法がなかなか把握できず、理解するのに結構苦労しました。
はじめはこんなに書くつもりじゃなかったんだけど、忘れたときにまた調べ直すのがたいへんだなって思ってまとめたら結構なボリュームになりました:sweat_drops:
実はこの記事が Qiita 初投稿。本格的に Qiita CLI を触るのはこれからなので、なにか気づいたら修正しようと思ってます。

同様のサービスを提供している Zenn とは実現の時期や開発経緯も異なるのか、設計思想が全く異なっていてとても~~おもしろ~~勉強になりました:blush:

最後に。この記事が私のようなビギナーの方の助けになれば幸いです。

[^1]: 特にローカル運用での投稿などは公式や他の方の記事の受け売りです。
[^2]: 読み方調べたら「ミーゼンプラス」らしいけど[何回聞いても聞こえない。](https://ja.forvo.com/word/mise-en-place/)
[^3]: [pnpm のブログ](https://pnpm.io/ja/blog/2021/12/29/yearly-update)で目標に Bower や Lerna のダウンロード数に勝つことを謳うなど攻めっ気のあるところ、面白いですね。
[^4]: Web エディタでないとできないこともあるようで、[困った方がいらっしゃいました](https://qiita.com/nomurasan/items/f35d739ed853827dd135)。同期は結構手間なので、運用はどちらかでシンプルに。
[^5]: まあgitで確認できますが。
[^6]: まだ mise の VSCode 拡張機能は導入していません。今度やってみたい。なるべく早めに。
[^7]: `brew pnpm` や `mise use --global pnpm` でシステム全体に適用するようにインストールすることもできます。私はグローバルにインストールしたことないです。
[^8]: pnpm のインストールは `mise use npm:pnpm` や `mise use pnpm:pnpm` など mise のバックエンドを指定してインストールする方法もあるようです。
[^9]: なぜログイン? 設定ファイル credentials.json への Qiita アクセストークンの書き込みだよね? 当初はホントのログインだった?
[^10]: 公式記事だと `"includePrivate" : true` は `qiita pull` のための設定と書かれてる。確かに `false` でも投稿はできたんだよね。でも Web エディタで変更後に pull できないから結局 `true` にしとかないと運用的にまずいんだよね。`qiita new` でできる新規記事のデフォルト変えれたらなあ。
[^11]: コマンド末尾に `2>&1 /dev/null` をつけて捨ててもいいけど予期しないエラーかもだし、確認できたほうがいいよね。
[^12]: html では [h1 は 1 ファイルに 1 つが推奨](https://developer.mozilla.org/ja/docs/Web/HTML/Reference/Elements/Heading_Elements#1_%E3%81%A4%E3%81%AE%E3%83%9A%E3%83%BC%E3%82%B8%E3%81%AB%E8%A4%87%E6%95%B0%E3%81%AE_h1_%E8%A6%81%E7%B4%A0%E3%82%92%E4%BD%BF%E7%94%A8%E3%81%97%E3%81%AA%E3%81%84)。記事ファイルで `#` を使って h1 にしてもエラーにはならないけど SEO 的にどうなんでしょう? 知らんけど。
[^13]: コードスパンの説明文(バッククオートのあとにコロン)とか note 3 種(`:::note info / warn / alert`) とかいいよね。
[^14]: どこにも書いてなかったんだよね。一般的な Markdown では、段落内で改行したいときは[行末に半角スペース2つ](https://daringfireball.net/projects/markdown/syntax#p)を置く。段落内の改行は無視される。Qiitaだと改行は全部反映されるみたい。
[^15]: Qiita CLI 登場前夜 [@ryokat3](https://qiita.com/ryokat3) さんが[Qiita Sync](https://qiita.com/ryokat3/items/d054b95f68810f70b136) というツールをリリースされてました。画像も扱えるように見えたのですが GitHub 上の画像リンクに変換していて、リポジトリを Private にしての運用できませんでした。残念。
[^16]: Markdown で `![img_alt](img_src)`、 html で `<img border="" />`, `<img style="border: none;" />`など試したけど枠は消えなかった。こちらからできることでは消せないのかな…
[^17]: GitHub 運用では GitHub Actions により GitHub のタスクランナーで `qiita publish --all` を実行し、GitHub の記事リモートリポジトリにある投稿対象のファイルのフロントマターを変更しています。コンテナか何かが動いてるみたいでその分時間がかかります。