フロントエンドの世界2024: Qiita CLIを利用した執筆環境 (おまけ)


## はじめに

はじめまして、WEB フロントエンドエンジニアの nuintee です。

この度本アドベントカレンダー[フロントエンドの世界 2024](https://qiita.com/advent-calendar/2024/frontend-assort-2024)」の記事を執筆するにあたり、[qiita-cli](https://github.com/increments/qiita-cli) を利用したので導入方法や執筆フローについて書きました。

## フロントエンドの世界 2024 について

「[フロントエンドの世界 2024](https://qiita.com/advent-calendar/2024/frontend-assort-2024)」は普段 [`Next.js`](https://nextjs.org/) を書いている筆者が、同じフロントエンドライブラリである [`Svelte(Kit)`](https://svelte.jp/docs/introduction), [`Remix`](https://remix.run/docs/en/main) ,[`SolidJS`](https://docs.solidjs.com/), [`Qwik(City)`](https://qwik.dev/)の 4 つにアソート形式で触れ、理解を深めていく様子を収めたアドベントカレンダーです。

![frontend-assort-2024-banner.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294810/7666d209-1aef-9ce5-c298-d8e60847e830.png)

## もくじ

- [はじめに](#はじめに)
- [フロントエンドの世界 2024 について](#フロントエンドの世界-2024-について)
- [もくじ](#もくじ)
- [Qiita CLI とは](#qiita-cli-とは)
- [Qiita CLI のメリット](#qiita-cli-のメリット)
- [Qiita CLI の導入](#qiita-cli-の導入)
- [使い方](#使い方)
- [便利な Tips](#便利な-tips)
- [全体的な執筆の流れ](#全体的な執筆の流れ)
- [参考](#参考)
- [おわりに](#おわりに)

## Qiita CLI とは

`Qiita CLI` は、ローカル環境で Qiita の記事を管理・執筆するための 公式 CLI ツールです。

記事を Markdown ファイルとして作成・編集・投稿できるため、エディタや Git を活用した効率的な作業が可能になります。

公式リポジトリ: [qiita-cli](https://github.com/increments/qiita-cli)

## Qiita CLI のメリット

**1. 記事を Git 管理できる**  
 記事のバージョン管理や変更履歴の記録が可能で、共同編集やバックアップにも最適です。

**2. ローカルエディタを活用できる**  
 好きなエディタで執筆可能。VSCode などの補完機能やプラグインを活かせます。

**3. 投稿・プレビューが簡単**  
 コマンドひとつで記事をプレビューしたり、Qiita に投稿できます。

**4. 効率的な執筆が可能**  
 記事テンプレートを使った執筆や、ワークフローの自動化も容易です。

## Qiita CLI の導入

### インストール

以下のコマンドで qiita-cli をインストールします。

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

### 初期セットアップ

初回起動時に必要なセットアップを行います。

```bash
npx qiita init
```

### Qiita トークンの発行

**1. トークン発行画面へアクセス**
Qiita にログインした状態で https://qiita.com/settings/tokens/new にアクセスします。

**2.名前とスコープの設定**
「アクセストークンの説明」でトークンに対してわかりやすい名前をつけます。

またスコープは `read_qiita`と `write_qiita`にチェックが入っていることを確認し、「発行する」を押してトークンを作成します。

![スクリーンショット 2024-12-21 19.37.22.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294810/d900db89-78a0-6e7b-d1f6-71740c0c0fac.png)

**3. トークンをコピー**
作成が完了すると個人用アクセストークンが表示されるのでコピーしておきます。

![token.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294810/9e5cf0d9-c0ac-4164-3997-20cb1cd44ff2.png)

### Qiita ログイン

作成したトークンを用いてターミナル上で Qiita にログインします。

```shell
npx qiita login
```

コマンド実行後トークンの入力を要求されるので指示に従います。

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

発行したトークンを入力: <発行したトークン>
```

トークンを用いたログインが完了すると、次のログが出力されます。

```shell:成功時のログ
ログインが完了しました 🎉
以下のコマンドを使って執筆を始めましょう！

🚀 コンテンツをブラウザでプレビューする
  npx qiita preview

🚀 新しい記事を追加する
  npx qiita new (記事のファイルのベース名)

🚀 記事を投稿、更新する
  npx qiita publish (記事のファイルのベース名)

💁 コマンドのヘルプを確認する
  npx qiita help
```

これで qiita-cli を利用する準備はできました。

## 使い方

### 記事のプレビュー

記事をローカルでプレビューするには以下を実行します。

```bash
qiita preview
```

[http://[::1]:8888](http://[::1]:8888) でリアルタイムプレビューが表示され、投稿前の記事を確認できます。

### 記事の投稿

執筆した記事を投稿するには以下を実行します。
※ 拡張子の `.md` は無しで大丈夫です。

```bash
qiita publish <記事ファイル名>

# 例: qiita publish document-1
```

## 便利な Tips

### VSCode でのプレビュー表示

VSCode に標準搭載の「Simple Browser」を使えば、プレビューをエディタ内で確認可能です。

**起動**
`shift + command + p`で VSCode のコマンドパレットを開き、`simple` と検索して出てきた「Simple Browser: Show」を実行します。

![スクリーンショット 2024-12-21 20.26.52.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294810/194a5588-a198-d796-8994-b49c7c41cfa4.png)

**プレビュー URL 入力**
URL の入力を求められるので `npx qiita preview`で起動したプレビューサーバーの 記事 URL を入力します。

:::note
※ ブラウザで [http://[::1]:8888/](http://[::1]:8888/) を開き、任意の記事を選択した際の URL をコピーして貼るのが簡単です。
:::

![スクリーンショット 2024-12-21 20.29.18.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294810/f5105738-025c-217e-f06b-1049fe4e55cb.png)

**記事とプレビューで画面分割**
Simple Browser が VSCode の別タブで開くので、
エディタと並べて表示したい場合はドラッグ&ドロップで画面の左・右のいずれかに持っていくと分割が可能です。

![スクリーンショット 2024-12-21 20.39.42.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294810/38b27b2a-6d7d-adfe-a2ff-957ee4c4ac71.png)

### hygen によるテンプレート生成

`hygen` を使うと、記事のテンプレート化が行えます。
※ 今回 hygen の導入方法については割愛します。(参考: [hygen](https://www.hygen.io/))

**アドベントカレンダー用のテンプレート**
今回使用したアドベントカレンダー用のテンプレートです。

```ejs:.hygen/generator/new/index.ejs.t
---
to: public/<%= filename %>.md
---
---
title: '<%= name %>'
tags:
  - 入門
  - チュートリアル
  - Svelte
private: true
updated_at: '<%= new Date().toISOString();%>'
organization_url_name: null
author: nuinteedev
id: null
slide: false
ignorePublish: false
---

## はじめに

はじめまして、WEB フロントエンドエンジニアの nuintee です。

この度かねてより関心があった Svelte に入門する覚悟が出来たので、
その学習過程をアドベントカレンダーにしてみました。

Svelte に少しでも興味のある方は、ぜひご覧ください。

## フロントエンドの世界 2024 について

「[フロントエンドの世界 2024](https://qiita.com/advent-calendar/2024/frontend-assort-2024)」は普段 [`Next.js`](https://nextjs.org/) を書いている筆者が、同じフロントエンドライブラリである [`Svelte(Kit)`](https://svelte.jp/docs/introduction), [`Remix`](https://remix.run/docs/en/main) ,[`SolidJS`](https://docs.solidjs.com/), [`Qwik(City)`](https://qwik.dev/)の 4 つにアソート形式で触れ、理解を深めていく様子を収めたアドベントカレンダーです。

![frontend-assort-2024-banner.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294810/7666d209-1aef-9ce5-c298-d8e60847e830.png)

## もくじ

1. xxx
2. yyyy


## おわりに

<!-- TODO: 振り返りコメント -->

また本シリーズを通してお気軽にコメントお待ちしております。
また完走賞も目指しているので是非応援お願いします！

---

この記事は [フロントエンドの世界 Advent Calendar 2024](https://qiita.com/advent-calendar/2024/frontend-assort-2024)の<%= index %>記事目です。
次の記事はこちら <!-- TODO: 📃 次記事のハイパーリンク -->
```

**記事生成コマンド**
テンプレートを元に記事を作成する `new` コマンドを設定しておきます。

```diff_json:package.json
{
  "name": "qiita-cli-articles",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
-   "test": "echo \"Error: no test specified\" && exit 1"
+   "new": "hygen generator new"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@qiita/qiita-cli": "^1.6.1"
  }
}
```

**記事生成の実行例**
`hygen` のテンプレートを元に記事を生成する例です。

テンプレート内の一部をコマンドライン引数でわたせるようにしています。

```shell
npm run new -- --filename article-1 --name "記事1" --index 1
```

**生成された記事**
指定した情報で記事が生成されました。

```md:public/article-1.md
---
title: '記事1'
tags:
  - 入門
  - チュートリアル
  - Svelte
private: true
updated_at: '2024-12-21T11:19:43.654Z'
organization_url_name: null
author: nuinteedev
id: null
slide: false
ignorePublish: false
---

## はじめに

はじめまして、WEB フロントエンドエンジニアの nuintee です。

この度かねてより関心があった Svelte に入門する覚悟が出来たので、
その学習過程をアドベントカレンダーにしてみました。

Svelte に少しでも興味のある方は、ぜひご覧ください。

## フロントエンドの世界 2024 について

「[フロントエンドの世界 2024](https://qiita.com/advent-calendar/2024/frontend-assort-2024)」は普段 [`Next.js`](https://nextjs.org/) を書いている筆者が、同じフロントエンドライブラリである [`Svelte(Kit)`](https://svelte.jp/docs/introduction), [`Remix`](https://remix.run/docs/en/main) ,[`SolidJS`](https://docs.solidjs.com/), [`Qwik(City)`](https://qwik.dev/)の 4 つにアソート形式で触れ、理解を深めていく様子を収めたアドベントカレンダーです。

![frontend-assort-2024-banner.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294810/7666d209-1aef-9ce5-c298-d8e60847e830.png)

## もくじ

1. xxx
2. yyyy


## おわりに

<!-- TODO: 振り返りコメント -->

また本シリーズを通してお気軽にコメントお待ちしております。
また完走賞も目指しているので是非応援お願いします！

---

この記事は [フロントエンドの世界 Advent Calendar 2024](https://qiita.com/advent-calendar/2024/frontend-assort-2024)の1記事目です。
次の記事はこちら <!-- TODO: 📃 次記事のハイパーリンク -->
```

:::note

- **--filename**: ファイル名 ([filename].md として生成されます。)
- **--name**: 記事名
- **--index**: 何記事目か (記事シリーズで使用)

:::

### Markdown All in One による目次の自動生成

[Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) は、VSCode 用の Markdown プラグインです。
いくつかの機能がありますが、今回は [Table of contents](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one#table-of-contents) 機能 (目次の自動生成) を利用しました。

**目次レベルの調整**
今回は H1 と H2 のみが目次として認識されるようにレベルを調整しました。

VSCode の設定ファイルに次の記述を追加することで設定が可能です。

(参考: [markdown.extension.toc.levels](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one#table-of-contents:~:text=markdown.extension.toc.levels))

```json:settings.json
{
  ...
  "markdown.extension.toc.levels": "1..2"
}
```

**自動目次生成**
目次を自動で生成するには、目次を追加したい箇所でコマンドパレットから `Markdown All in One: Create Table of Contents`コマンドを実行します。

:::note
コマンドパレットの起動: `shift + command + p`
:::

![スクリーンショット 2024-12-21 20.53.12.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294810/dff4af8c-5748-12a6-f051-91c217378df3.png)

実行することで H1,H2 の記述から自動で目次を作成してくれます。(本記事での生成例)

![スクリーンショット 2024-12-21 20.56.45.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294810/4673d5d5-a326-03b0-0b09-38c5a3d2475b.png)

## 全体的な執筆の流れ

**1. 記事の作成**
hygen テンプレートをもとに新しい記事を作成します。([参照](https://qiita.com/nuinteedev/private/ad236fbb33ee16bc1165#hygen-%E3%81%AB%E3%82%88%E3%82%8B%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88%E7%94%9F%E6%88%90:~:text=1.6.1%22%0A%20%20%7D%0A%7D-,%E8%A8%98%E4%BA%8B%E7%94%9F%E6%88%90%E3%81%AE%E5%AE%9F%E8%A1%8C%E4%BE%8B,-hygen%20%E3%81%AE%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88))
`npm run new <フラグ>`

**2. 執筆とプレビュー**
エディタで記事を編集しつつ画面分割でプレビューを見ながら執筆を進めます。([参照](https://qiita.com/nuinteedev/private/ad236fbb33ee16bc1165#vscode-%E3%81%A7%E3%81%AE%E3%83%97%E3%83%AC%E3%83%93%E3%83%A5%E3%83%BC%E8%A1%A8%E7%A4%BA:~:text=%E3%81%8C%E7%B0%A1%E5%8D%98%E3%81%A7%E3%81%99%E3%80%82-,%E8%A8%98%E4%BA%8B%E3%81%A8%E3%83%97%E3%83%AC%E3%83%93%E3%83%A5%E3%83%BC%E3%81%A7%E7%94%BB%E9%9D%A2%E5%88%86%E5%89%B2,-Simple%20Browser%20%E3%81%8C))

**2. git commit / git push**
章ごとやキリの良いタイミングで記事を commit や push します。

**3. 投稿**
完成した記事を `npx qiita publish <ファイル名>` コマンドで投稿します。([参照](#%E8%A8%98%E4%BA%8B%E3%81%AE%E6%8A%95%E7%A8%BF))
※ 投稿後は更新日時等で差分が出るので再度 commit & push をする必要があります。

## 参考

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

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

## おわりに

qiita-cli を用いた執筆はとても体験が良かったです。

テンプレートを使用したり、複数ファイルまとめて編集できたりするので、
執筆時間を大幅に短縮できました。

アドベントカレンダーを書く上で非常に効率的に進められたので、導入して良かったです。

記事を定期的に書いている方や一人アドベントカレンダーには特におすすめです。

---

また本シリーズを通してお気軽にコメントお待ちしております。
また完走賞も目指しているので是非応援お願いします！

この記事は [フロントエンドの世界 Advent Calendar 2024](https://qiita.com/advent-calendar/2024/frontend-assort-2024)の 24 記事目です。  
次の記事はこちら: [フロントエンドの世界 2024: フロントエンドフレームワークの比較 (おわり) Qiita](https://qiita.com/nuinteedev/private/82dff28712dd160ed587)