🔨

Zenn CLIで記事・本を管理する方法

commits7 min read 36

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

📘 Zenn CLI を導入する →

CLI で記事(article)を管理する

ファイルの配置ルール

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

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

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

記事の作成

まだarticlesディレクトリが存在しない場合は、事前にnpx zenn initを実行してください(参考:zenn-cli のセットアップ

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

$ 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 でのデプロイがスキップされます。

記事の更新

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

リポジトリの変更が zenn.dev に反映されるまでにしばらく時間がかかります。ダッシュボードからデプロイのステータスをご確認ください。

また、未ログイン状態ではしばらくキャッシュされた古い内容が表示される可能性があります。時間を置いた後にリロードしてご確認ください。

記事の削除

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


CLI で本(book)を管理する

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

本のディレクトリ構成

まだbooksディレクトリが存在しない場合は、事前にnpx zenn initを実行してください(参考:zenn-cli のセットアップ

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.mdexample2.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.yamltoc_depth: 0と記載すると各チャプターの目次を非表示にできます。toc_depth: 1とすると「h1」見出しだけが目次に表示されます。この値は03の範囲で指定する必要があります。

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

🖼️ カバー画像

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

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

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

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

---
title: "チャプターのタイトル"
---
ここからチャプター本文
本文に画像を挿入するには

GitHub 連携時に本文で画像を使う際は画像のアップロードページをご利用ください。

有料の本で一部のチャプターを無料公開する場合は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でチャプターの並び順を指定すると、ディレクトリ内が煩雑になってしまうという場合には、ファイル名で並び順を制御することもできます。

詳しく読む

ファイル名をチャプター番号.slug.mdという形にすると、その順番通りにチャプターが表示されます。

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

この方法でデプロイを行う場合、config.yamlchaptersは空にしておく必要があります。

デプロイ時に以下のようなファイルの読み方をするためです。

  • config.yamlchaptersが指定されている場合 => 指定通りにslug.mdを読みにいく
  • config.yamlchaptersが空の場合 => 番号.slug.mdを読みにいく

複数のチャプターで同じ slug を使うことはできません。例えば2.summary.md3.summary.mdという同一 slug のファイルがあった場合、どちらか片方しか反映されません。

関連する GitHub Issue →

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

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

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

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

本の slug はa-z0-9、ハイフン-、アンダースコア_の 12〜50 字の組み合わせにする必要があります

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

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

$ npx zenn preview

最大チャプター数

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

本の更新

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

リポジトリの変更が zenn.dev に反映されるまでにしばらく時間がかかります。ダッシュボードからデプロイのステータスをご確認ください。

また、未ログイン状態ではしばらくキャッシュされた古い内容が表示される可能性があります。時間を置いた後にリロードしてご確認ください。

本の削除

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

GitHubで編集を提案

Discussion

オンラインエディタで投稿してしまった記事を何らかの方法でcloneしたりpullしたりはできないのでしょうか?

現時点では対応しておらず手動でコピペする必要があります。課題は感じているので将来対応予定です。

有料で本を出す場合は、管理するリポジトリはプライベートにしておいたほうが良い感じですかね?

そうですね。有料販売する場合はプライベートリポジトリにされることをおすすめします。

なるほどですね、ありがとうございます!😄

本文で画像を使う際は"画像のアップロードページ"を利用したほうがいいのでしょうか?

他にもGitHubのリポジトリに置く方法やGitHubのIssueに貼り付けてリンクだけ取得する方法などがあるように思いますが。

ご自身でGitHubやGyazoなどリンク切れにならなさそうな場所に画像をアップロードして、マークダウンにURLを貼り付ける形でもOKです。
現状だとリポジトリ同期のタイミングで画像をまとめてアップロードするのは(負荷などの理由から)難しいため、アップロードページを用意しているという状況です。

book をGithubで執筆した場合、チャプターごとに無料公開する設定は可能でしょうか。
管理画面にはそういった項目が見当たりませんでした。

すみません、ドキュメントに書き忘れていました。
チャプター番号.mdファイルにて

---
title: hoge
free: true
---

と書くとそのチャプターは無料になります。

素早い返信、ありがとうございます。

こちらis_freeからfreeに変更しました。is_freeでも動くようにしてありますが、できればfreeを使っていただければと思います。

Bookを最後まで読むとどんなものができるかの動画をまえがきに記したいのですがその場合はgif画像にするのが良いのでしょうか? それともyoutubeの限定公開なりに動画をアップしてそこへのリンクを貼るのが良いのでしょうか?

gif画像だと容量制限(現在1.5MBだったと思います)があったと思うので、長い動画であればYouTubeの方が適しているかもしれません。現時点ではsummaryに動画や画像の埋め込みはできないので、チャプター1を無料公開にしてそこに画像やYouTube埋め込みをするのが良いと思います。

迅速な返信有難うございます
記事の中にある途中経過の動画も長いので諸々Youtubeにアップしようと思います

質問です、有料Bookの中の無料公開チャプターの一部を別の記事として投稿しようと思うのですが利用規約第四条 11のスパムとみなされる行為に抵触しないか若干不安です。

遅くなりすみません。
いくつも同内容の記事や本を作成しない限り(もしくは明らかにスパム的な意図があると判断される場合を除き)スパム行為とはみなすことはありませんのでご安心ください。

回答くださりありがとうございます!

記事に掲載する画像をローカルの articles/ の下に置いたのですが、CLI でプレビューしたときに表示させたいのですが、URLの指定方法がわからないでいます。なにか方法はありますか?.mdファイルはVS Codeで編集して、github連携しています。

現時点ではディレクトリ内の画像を相対パスで読み込むことはできず、下記のページから画像をアップロードしてURLを貼り付ける必要があります。

https://zenn.dev/dashboard/uploader

※ GitHubやGyazoなどから画像を読み込んでもOKです。

了解しました。ありがとうございます。

本のチャプターを更新したいのですが、Zenn.devへ反映されません。
1ヶ月ほど前までは同じ方法で反映されていたと思うのですが、、
どうしたらよいでしょうか?

ダッシュボードには↓のようにリポジトリ内のファイルが取得できませんでした。articlesディレクトリが存在しているか確認してくださいと表示されます。

https://twitter.com/o_matsu555/status/1327876352356204544?s=20

GitHubのアカウントはhttps://github.com/ryosuke-mで合っていますか?画像を見る限り、https://github.com/ryosuke-m/zenn-contentsからデータを取得しようとしていると思うのですがhttps://github.com/ryosuke-mというGitHubアカウント自体が存在していないようです。

ダッシュボード - デプロイの下部から「連携を解除する」を実行してもらって、再連携してみていただけますか?
※再連携してもデータは残ります。

早速ありがとうございます!!再連携すると無事に更新が反映されました。
先日githubのアカウント名を変更していたことを忘れていました。大変失礼しました。

既にブラウザで途中まで書いた本や記事を,途中から zenn CLI に移して使い始めることはできますか?

可能ですが、現時点だと少し面倒なステップを踏む必要があります。(そのうちコミット機能をつけたいと思っています)

記事(article)の場合以下のようになります。

  1. 各記事のslug(URL内のユニークな文字列)と同じファイル名のマークダウンファイルを作成します。例: gj7hkdjkfs8okbxz.md
  2. タイトルや本文をファイルにコピペします。この内容で既存の記事が上書きされるため、本文は確実にコピペするようにしてください。空のマークダウンでコミットすると既存の内容が消えてしまう可能性があります。
  3. ZennのダッシュボードからGitHubと連携します。なお連携だけではデータの上書きはされません。
  4. リポジトリへなんらかのコミットをするとzenn.devへの同期がされます。

本についても各チャプターの本文をマークダウンファイルへと一つずつコピペしていく必要があります。ディレクトリ名と本のスラッグを合わせることで既存のLikeなどのデータを引き継げます。

チャプターのマークダウンファイルについては新しくスラッグを作ってしまうのが良いと思います(各チャプターのURLが変わるだけです)。本単位で上書きが行われるため、全チャプターの本文をコピペしてからコミットしていただくようお願いします。

なお、本については意図せず全チャプターの内容が上書きされて消えてしまうことを防ぐためにcofing.yamlallow_override: trueを指定する必要があります。

できました!ありがとうございます.

問い合わせする場所が分からなかったので、ここに書かせていただきます。

zennが提供する検索で記事が引っかかりにくいようです。
小文字大文字、分かち書きなど。

https://twitter.com/sasanoha____/status/1339632869476450306

ありがとうごうざいます。頑張ってください!

ログインするとコメントできます