Zenn CLIで記事・本を管理する方法
このページではZenn CLIの使い方とコマンドの一覧を紹介します。まだインストールしていない方は下記のリンク先をご覧ください。
CLIで記事(article)を管理する
ファイルの配置ルール
1つの記事の内容は、1つのマークダウンファイル(◯◯.md
)で管理します。ファイルはarticles
という名前のディレクトリ内に含める必要があります。
.
└─ articles
├── example-article1.md
└── example-article2.md
具体的な例として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 ✨
slugはa-z0-9
とハイフン-
の12〜50字の組み合わせにする必要があります
本文に画像を挿入するには
GitHub連携時に本文で画像を使う際は画像のアップロードページをご利用ください。
プレビューする
本文の執筆は、ブラウザでプレビューしながら確認できます。ブラウザでプレビューするためには次のコマンドを実行します。
$ npx zenn preview # プレビュー開始
👆 このように各記事をプレビューをしながら執筆できます。
デフォルトではlocalhost:8000
で立ち上がりますがnpx zenn preview --port 3000
というようにポート番号の指定もできます。
記事を公開する
記事をzenn.dev上で公開するにはpublished
オプションがtrue
になっていることを確認したうえで、ファイルをコミットし、Zennと連携されているGitHubリポジトリにプッシュします。
Zennと連携したリポジトリの登録ブランチにプッシュされると、同期(デプロイ)が開始されます。
デプロイ履歴はダッシュボードから見ることができます。デプロイ時にエラーが発生している場合もここから見る必要があります。
なおコミットメッセージに[ci skip]
もしくは[skip ci]
が含まれているとZennでのデプロイがスキップされます。
記事の更新
記事の更新を行う場合も、マークダウンファイルを編集し、GitHubリポジトリへプッシュするだけでOKです。このときslugが同一のものでないと別の記事として作成されてしまうので注意しましょう。
リポジトリの変更がzenn.devに反映されるまでにしばらく時間がかかります。ダッシュボードからデプロイのステータスをご確認ください。
また、未ログイン状態ではしばらくキャッシュされた古い内容が表示される可能性があります。時間を置いた後にリロードしてご確認ください。
記事の削除
削除はダッシュボードから行います。安全のため、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
内に作ることになります。
実際の例としてZennのドキュメント用リポジトリが参考になるかもしれません。
本の各ファイルの役割
📄 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: "チャプターのタイトル"
---
ここからチャプター本文
本文に画像を挿入するには
GitHub連携時に本文で画像を使う際は画像のアップロードページをご利用ください。
有料の本でチャプターを無料公開する場合はfree: true
を指定してください。
---
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
でチャプターの並び順を指定すると、ディレクトリ内が煩雑になってしまうという場合には、ファイル名で並び順を制御することもできます。
詳しく読む
ファイル名をチャプター番号.slug.md
という形にすると、その順番通りにチャプターが表示されます。
# 具体的な例
books
└── my-awesome-book
├── config.yaml
├── 1.intro.md
├── 2.foo.md
└── 3.bar.md
この方法でデプロイを行う場合、config.yaml
のchapters
は空にしておく必要があります。
デプロイ時に以下のようなファイルの読み方をするためです。
-
config.yaml
でchapters
が指定されている場合 => 指定通りにslug.md
を読みにいく -
config.yaml
でchapters
が空の場合 =>番号.slug.md
を読みにいく
複数のチャプターで同じslugを使うことはできません。例えば2.summary.md
と3.summary.md
という同一slugのファイルがあった場合、どちらか片方しか反映されません。
本の雛形をコマンドで作成する
本の構成は少し複雑ですが、下記のコマンドを使えば雛形を作成できます。
$ npx zenn new:book
# 本のslugを指定する場合は以下のようにします。
# npx zenn new:book --slug ここにスラッグ
あとは1つずつファイルを作成していけばOKです。
本のslugはa-z0-9
とハイフン-
の12〜50字の組み合わせにする必要があります
本と各チャプターをプレビューする
以下のコマンドにより、ブラウザ上でプレビューしながら執筆できます。
$ npx zenn preview
本の更新
本の更新を行う場合も、ファイルを変更し、GitHubリポジトリへプッシュするだけでOKです。このときslug(ディレクトリ名)が同一のものでないと別の本として作成されてしまうので注意しましょう。
リポジトリの変更がzenn.devに反映されるまでにしばらく時間がかかります。ダッシュボードからデプロイのステータスをご確認ください。
また、未ログイン状態ではしばらくキャッシュされた古い内容が表示される可能性があります。時間を置いた後にリロードしてご確認ください。
本の削除
削除はダッシュボードから行います。books
ディレクトリからファイルを削除してもzenn.dev上では削除はされません。