1 つの記事の内容は、1 つのmarkdownファイル（◯◯.md）で管理します。ファイルはarticlesという名前のディレクトリ内に含める必要があります。
.
└─ articles
├── example-article1.md
└── example-article2.md
具体的な例としてZenn のドキュメント用リポジトリを見ると分かりやすいかもしれません。
:::message
まだarticlesディレクトリが存在しない場合は、事前にnpx zenn initを実行してください（参考：zenn-cli のセットアップ）
:::
以下のコマンドによりmarkdownファイルを簡単に作成できます。
$ npx zenn new:articlearticles/ランダムな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 ✨:::message
slug はa-z0-9、ハイフン-、アンダースコア_の 12〜50 字の組み合わせにする必要があります
:::
:::details 本文に画像を挿入するには 以下のいずれかの方法で本文に画像を挿入できます。
- Zennの画像のアップロードページ（要ログイン）から画像をアップロードしてURLを貼り付ける
- GitHubリポジトリ内に画像を配置する
- Gyazoなどの外部サービスにアップロードした画像のURLを貼り付ける
:::
本文の執筆は、ブラウザでプレビューしながら確認できます。ブラウザでプレビューするためには次のコマンドを実行します。
$ npx zenn preview # プレビュー開始👆 このように各記事をプレビューをしながら執筆できます。
:::message
デフォルトではlocalhost:8000で立ち上がりますがnpx zenn preview --port 3000というようにポート番号の指定もできます。
:::
:::message
npx zenn preview --no-watchのようにすることでファイルの監視と自動リロードが無効になります。
:::
記事を zenn.dev 上で公開するにはpublishedオプションがtrueになっていることを確認したうえで、ファイルをコミットし、Zenn と連携されている GitHub リポジトリにプッシュします。
Zenn と連携したリポジトリの登録ブランチにプッシュされると、同期（デプロイ）が開始されます。
:::message デプロイ履歴はダッシュボードから見ることができます。デプロイ時にエラーが発生している場合もここから見る必要があります。 :::
なおコミットメッセージに[ci skip]もしくは[skip ci]が含まれていると Zenn でのデプロイがスキップされます。
公開時間を指定して記事を公開するには、Front Matterにて published を true にした上で、 published_at を指定します。published_at のフォーマットは、 YYYY-MM-DD または YYYY-MM-DD hh:mm です。日付だけを指定した場合、時刻は 00:00 となります。
published: true # trueを指定する
published_at: 2050-06-12 09:03 # 未来の日時を指定するこの状態で、GitHubリポジトリへプッシュすると、zenn.dev上で記事が公開予約状態となり、公開予約時刻が過ぎると自動的に記事が公開されます。
他のブログサービスなどからzenn.devに記事を移行する際に公開日時を維持したい場合、Front Matterにて published_at に過去の日時を指定することで、zenn.dev上での公開日時を指定することができます。published_at のフォーマットは、 YYYY-MM-DD または YYYY-MM-DD hh:mm です。日付だけを指定した場合、時刻は 00:00 となります。
published: true # true/falseどちらでもOKです
published_at: 2010-01-01 08:00 # 過去の日時を指定する:::message 公開日時の指定は一度しかできず、既に設定された値を変更することはできません。 :::
記事の更新を行う場合も、markdownファイルを編集し、GitHub リポジトリへプッシュするだけで OK です。このとき slug が同一のものでないと別の記事として作成されてしまうので注意しましょう。
:::message alert リポジトリの変更が zenn.dev に反映されるまでにしばらく時間がかかります。ダッシュボードからデプロイのステータスをご確認ください。
また、未ログイン状態ではしばらくキャッシュされた古い内容が表示される可能性があります。時間を置いた後にリロードしてご確認ください。 :::
削除はダッシュボードから行います。安全のため、articlesディレクトリからmarkdownファイルを削除しても zenn.dev 上では削除はされません。
Zenn の本は複数のチャプターで構成されます。
:::message
まだ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.mdやexample2.mdは各チャプターファイルの例です（のちほど詳しく説明します）。
これが 1 冊の本のファイル構成です。複数の本を作成するためには、同様の構成のディレクトリを複数books内に作ることになります。
:::message 実際の例としてZenn のドキュメント用リポジトリが参考になるかもしれません。 :::
本の設定ファイルです。以下のように記入してください。
title: "本のタイトル"
summary: "本の紹介文"
topics: ["markdown", "zenn", "react"] # トピック（5つまで）
published: true # falseだと下書き
price: 0 # 有料の場合200〜5000
chapters:
- example1 # チャプター1
- example2 # チャプター2
- example3 # チャプター3title: 本のタイトルを入力します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です。他のサイズにした場合も最終的にこのサイズにリサイズされます。
各チャプターのファイル名は「a-z0-9、ハイフン-、アンダースコア_の 1〜50 字の組み合わせ」+ .mdとします。この文字列は URL の一部となります。例えばabout.mdのチャプターの URL は/ユーザー名/本のスラッグ/viewer/aboutとなります。
各チャプターのmarkdownファイルには Front Matter でタイトルを指定し、その下に本文を書いていきます。
---
title: "チャプターのタイトル"
---
ここからチャプター本文:::details 本文に画像を挿入するには 以下のいずれかの方法で本文に画像を挿入できます。
- Zennの画像のアップロードページ（要ログイン）から画像をアップロードしてURLを貼り付ける
- GitHubリポジトリ内に画像を配置する
- Gyazoなどの外部サービスにアップロードした画像のURLを貼り付ける :::
有料の本で一部のチャプターを無料公開する場合はfree: trueを指定してください。本の価格が ¥0（無料）のときはこの設定は無視されます。
---
title: "タイトル"
free: true
---
たとえば、次の 4 つのチャプターファイルを作ったとします。
abstract.mdresults.mdintroduction.mdconclusion.md
表示順はconfig.yamlで指定します。
# config.yaml
...省略...
chapters:
- introduction
- results
- conclusion👆 zenn.dev 上ではchaptersに配列で指定された順番にチャプターが並ぶことになります。この例の場合「introduction → results → conclusion」の順に並びます。abstract.mdは指定されていないため同期されません。
config.yamlでチャプターの並び順を指定すると、ディレクトリ内が煩雑になってしまうという場合には、ファイル名で並び順を制御することもできます。
::::details 詳しく読む
ファイル名をチャプター番号.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を読みにいく
::: message alert
複数のチャプターで同じ slug を使うことはできません。例えば2.summary.mdと3.summary.mdという同一 slug のファイルがあった場合、どちらか片方しか反映されません。
:::
::::
本の構成は少し複雑ですが、下記のコマンドを使えば雛形を作成できます。
$ npx zenn new:book
# 本のslugを指定する場合は以下のようにします。
# npx zenn new:book --slug ここにスラッグあとは 1 つずつファイルを作成していけば OK です。
:::message
本の slug はa-z0-9、ハイフン-、アンダースコア_の 12〜50 字の組み合わせにする必要があります
:::
以下のコマンドにより、ブラウザ上でプレビューしながら執筆できます。
$ npx zenn preview本のチャプターは1冊あたり最大100個まで作成できます。
本の更新を行う場合も、ファイルを変更し、GitHub リポジトリへプッシュするだけで OK です。このとき slug（ディレクトリ名）が同一のものでないと別の本として作成されてしまうので注意しましょう。
:::message alert リポジトリの変更が zenn.dev に反映されるまでにしばらく時間がかかります。ダッシュボードからデプロイのステータスをご確認ください。
また、未ログイン状態ではしばらくキャッシュされた古い内容が表示される可能性があります。時間を置いた後にリロードしてご確認ください。 :::
削除はダッシュボードから行います。booksディレクトリからファイルを削除しても zenn.dev 上では削除はされません。