このページでは Zenn CLI の使い方とコマンドの一覧を紹介します。まだインストールしていない方は下記のリンク先をご覧ください。

📘 Zenn CLI を導入する →

aaa

CLI で記事（article）を管理する

ファイルの配置ルール

1 つの記事の内容は、1 つのマークダウンファイル（◯◯.md）で管理します。ファイルはarticlesという名前のディレクトリ内に含める必要があります。

.
└─ articles
   ├── example-article1.md
   └── example-article2.md

memo

具体的な例としてZenn のドキュメント用リポジトリを見ると分かりやすいかもしれません。

記事の作成

以下のコマンドによりマークダウンファイルを簡単に作成できます。

$ npx zenn new:article

articles/ランダムなslug.mdというファイルが作成されます。slug（スラッグ）はその記事のユニークな ID のようなものです。詳しくは「Zenn の slug とは」をご覧ください。

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

---
title: "" # 記事のタイトル
emoji: "😸" # アイキャッチとして使われる絵文字（1文字だけ）
type: "tech" # tech: 技術記事 / idea: アイデア記事
topics: [] # タグ。["markdown", "rust", "aws"]のように指定する
published: true # 公開設定（falseにすると下書き）
---
ここから本文を書く

👆 ファイルの上部には---に挟まれる形で記事の設定（Front Matter）が含まれています。ここに記事のタイトル（title）やトピックス（topics）などをyaml 形式で指定することになります。

コマンド実行時に記事の Front Matter をオプションで指定することもできます。

$ npx zenn new:article --slug 記事のスラッグ --title タイトル --type idea --emoji ✨

プレビューする

本文の執筆は、ブラウザでプレビューしながら確認できます。ブラウザでプレビューするためには次のコマンドを実行します。

$ npx zenn preview # プレビュー開始

👆 このように各記事をプレビューをしながら執筆できます。

記事を公開する

記事を zenn.dev 上で公開するにはpublishedオプションがtrueになっていることを確認したうえで、ファイルをコミットし、Zenn と連携されている GitHub リポジトリにプッシュします。
Zenn と連携したリポジトリの登録ブランチにプッシュされると、同期（デプロイ）が開始されます。

なおコミットメッセージに[ci skip]もしくは[skip ci]が含まれていると Zenn でのデプロイがスキップされます。

記事の更新

記事の更新を行う場合も、マークダウンファイルを編集し、GitHub リポジトリへプッシュするだけで OK です。このとき slug が同一のものでないと別の記事として作成されてしまうので注意しましょう。

記事の削除

削除はダッシュボードから行います。安全のため、articlesディレクトリからマークダウンファイルを削除しても zenn.dev 上では削除はされません。

CLI で本（book）を管理する

Zenn の本は複数のチャプターで構成されます。

本のディレクトリ構成

GitHub リポジトリで本のデータを管理する場合は、次のようなディレクトリ構成にします。

.
├─ articles
└─ books
   └── 本のスラッグ
       ├── config.yaml # 本の設定
       ├── cover.png　# カバー画像（JPEGかPNG）
       └── チャプターのスラッグ.md # 各チャプター

具体的には、以下のようになります。

# 具体的な例
books
└── my-awesome-book
    ├── config.yaml
    ├── cover.png
    ├── example1.md
    ├── example2.md
    └── example3.md

👆example1.mdやexample2.mdは各チャプターファイルの例です（のちほど詳しく説明します）。

これが 1 冊の本のファイル構成です。複数の本を作成するためには、同様の構成のディレクトリを複数books内に作ることになります。

本の各ファイルの役割

📄 config.yaml

本の設定ファイルです。以下のように記入してください。

title: "本のタイトル"
summary: "本の紹介文"
topics: ["markdown", "zenn", "react"] # トピック（5つまで）
published: true # falseだと下書き
price: 0 # 有料の場合200〜5000
chapters:
  - example1 # チャプター1
  - example2 # チャプター2
  - example3 # チャプター3

• title : 本のタイトルを入力します
• summary : 本の紹介文を入力します。これは有料の本であっても公開されます
• topics : トピック（タグ）を 5 つまで指定します
• published : 公開する場合はtrueにします
• price : たとえば本を 1000 円で販売するときはprice: 1000と記載します（200〜5000 の間で 100 円単位で設定する必要があります）
• chapters : チャプターの並び順を配列で指定します（入れ子には未対応）。ここに指定されなかったチャプターは zenn.dev に同期されません
• toc_depth : 以下の説明をご覧ください

🚀 目次の表示設定

2020/10/26 から、チャプターごとの目次を表示できるようになりました。デフォルトでは「h1」と「h2」見出しまで目次に表示されます。

config.yamlでtoc_depth: 0と記載すると各チャプターの目次を非表示にできます。toc_depth: 1とすると「h1」見出しだけが目次に表示されます。この値は0〜3の範囲で指定する必要があります。

※ この値は本全体での設定になります。チャプターごとに別の設定をすることはできません。

🖼️ カバー画像

本のカバー画像（表紙）はcover.pngもしくはcover.jpegというファイル名で配置します。
推奨の画像サイズは幅 500px・高さ 700pxです。他のサイズにした場合も最終的にこのサイズにリサイズされます。

📄 各チャプターのファイル（◯◯.md）

各チャプターのファイル名は「a-z0-9、ハイフン-、アンダースコア_の 1〜50 字の組み合わせ」+ .mdとします。この文字列は URL の一部となります。例えばabout.mdのチャプターの URL は/ユーザー名/本のスラッグ/viewer/aboutとなります。

各チャプターのマークダウンファイルには Front Matter でタイトルを指定し、その下に本文を書いていきます。

---
title: "チャプターのタイトル"
---
ここからチャプター本文

有料の本で一部のチャプターを無料公開する場合はfree: trueを指定してください。本の価格が ¥0（無料）のときはこの設定は無視されます。

---
title: "タイトル"
free: true
---

具体的な例

たとえば、次の 4 つのチャプターファイルを作ったとします。

• abstract.md
• results.md
• introduction.md
• conclusion.md

表示順はconfig.yamlで指定します。

# config.yaml
...省略...
chapters:
  - introduction
  - results
  - conclusion

👆 zenn.dev 上ではchaptersに配列で指定された順番にチャプターが並ぶことになります。この例の場合「introduction → results → conclusion」の順に並びます。abstract.mdは指定されていないため同期されません。

ファイル名（チャプター番号.slug.md）で並び順を管理することも

config.yamlでチャプターの並び順を指定すると、ディレクトリ内が煩雑になってしまうという場合には、ファイル名で並び順を制御することもできます。

# 具体的な例
books
└── my-awesome-book
    ├── config.yaml
    ├── 1.intro.md
    ├── 2.foo.md
    └── 3.bar.md

本の雛形をコマンドで作成する

本の構成は少し複雑ですが、下記のコマンドを使えば雛形を作成できます。

$ npx zenn new:book
# 本のslugを指定する場合は以下のようにします。
# npx zenn new:book --slug ここにスラッグ

あとは 1 つずつファイルを作成していけば OK です。

本と各チャプターをプレビューする

以下のコマンドにより、ブラウザ上でプレビューしながら執筆できます。

$ npx zenn preview

最大チャプター数

本のチャプターは 1 冊あたり最大 100 個まで作成できます。

本の更新

本の更新を行う場合も、ファイルを変更し、GitHub リポジトリへプッシュするだけで OK です。このとき slug（ディレクトリ名）が同一のものでないと別の本として作成されてしまうので注意しましょう。

本の削除

削除はダッシュボードから行います。booksディレクトリからファイルを削除しても zenn.dev 上では削除はされません。

CLI で画像を管理する

CLI で画像を管理すると、GitHub リポジトリへプッシュすることで、リポジトリ内で管理されている画像が zenn.dev にアップロードされます。

画像ファイルの配置ルール

画像ファイルはリポジトリ直下の images ディレクトリに配置します。 images ディレクトリの中の構造に制限はありません。内部のディレクトリ名やファイル名に規則はありませんが、拡張子だけはチェック対象となります。

.
└─ images
   ├── example-image1.png
   └── example-article-1
       └─ image1.png

画像ファイルの制限事項

画像ファイルの制限は以下のとおりです。違反する場合はデプロイ時にエラーとなります。

• ファイルサイズは 3MB 以内
• 対応する拡張子は .png .jpg .jpeg .gif のみ

画像の参照方法

画像は、記事の本文や、本のチャプターの本文で参照することができます。参照するには、 /images/ から始まるパスを指定します。相対パスでは指定しないようご注意ください。

# 正しい指定方法

![](/images/example-image1.png)
![](/images/example-article-1/image1.png)

# 誤った指定方法

![](../images/example-image1.png)
![](//images/example-image1.png)

画像のデプロイ

GitHub リポジトリにプッシュすることで、画像が zenn.dev にアップロードされ、参照した記事や本に反映されます。

GitHub リポジトリから画像を削除すると、zenn.dev 上からも画像は削除されます。記事や本から参照されている画像を削除しないようご注意ください。

画像を差し替える場合、デプロイ完了から最大 1 分程度、古い画像が表示されることがあります。