✨

GitHub と連携させて Zenn のコンテンツをそれっぽく管理する

2023/07/01に公開

Zenn

idea

はじめに

「そろそろ Zenn デビューすっか！」 と思い立ったのをきっかけに、勢いでローカル執筆環境を構築してみましたので、作業内容を練習がてら記事にしていこうと思います。（何番煎じなんだろ...笑）

ローカル執筆環境に関する記事は色々と挙がっていますが、ひとまず公式を参考に進めました。

なお構築手順の全体像としては、以下の通りです。

まぁ公式が説明している手順をそのままなぞっているだけなので、そんなに複雑なことはしていませんが、興味ある方は最後までよろしくどうぞ 🙏

事前準備

執筆環境を構築するにあたって、以下は事前に準備してください。

お好きなテキストエディタ（特にこだわりがなければ VSCode で良いと思います）
GitHub のアカウント登録
Zenn のアカウント登録
Node.js のインストール
- 「Zenn CLI」のインストールに v14以上が必要

1. GitHub リポジトリと連携

まず当たり前ですが、GitHub リポジトリと Zenn を連携させる 必要があります。

具体的な手順は、以下の記事に書いてありますのでそちらの通りに進めていただければ大丈夫かと思います。

1 つ注意点としては、リポジトリの連携画面では必ずOnly select repositoriesを選んで連携したいリポジトリを選んでください。

All repositoriesを選んじゃうとたぶんうまくいきませんのでご注意を。

連携が完了すると以下のような画面になります。

2. Zenn CLI をインストール

次に、ローカルでの執筆時にスムーズに markdown ファイルを作成したり、コンテンツをプレビューしたりするために「Zenn CLI」を導入していきます。

https://github.com/zenn-dev/zenn-editor

まずは先程作ったリポジトリをお好きなディレクトリ上にクローンしましょう。

$ git clone https://github.com/xxxxxxxx/zenn-content.git
Cloning into 'zenn-content'...
warning: You appear to have cloned an empty repository.

その後、ディレクトリに移動して「Zenn CLI」をインストールし、セットアップコマンドを入力します。

$ cd zenn-content/
$ npm init --yes
$ npm install zenn-cli
$ npx zenn init

  🎉  Done!
  早速コンテンツを作成しましょう

  👇  新しい記事を作成する
  $ zenn new:article

  👇  新しい本を作成する
  $ zenn new:book

  👇  投稿をプレビューする
  $ zenn preview

こちらのセットアップが終わると、以下のようにREADME.mdや.gitignoreのほか、articlesやbooksという名前のディレクトリが作成されます。

このディレクトリの中に markdown ファイル（●●.md）を入れていくことになります。

project-name/
    ├─articles/
    |   ├── example-article1.md
    |   └── example-article2.md
    ├─books/
    |    └── my-awesome-book
    |        ├── config.yaml
    |        ├── cover.png
    |        ├── example1.md
    |        ├── example2.md
    |        └── example3.md
    ├─node_modules/
    ├─.gitignore
    ├─package-logck.json
    ├─package.json
    └ README.md

こちらも基本的には、以下の記事通りに進めていけばたぶん大丈夫かと思います。

3. 記事を書く

記事ファイルの作成

では記事ファイルを作成して、記事を実際に書いていきましょう。

記事ファイルの作成には、以下のコマンドを使用します。

$ npx zenn new:article

これによりarticles/ランダムなslug.mdというファイルが生成されます。

ただこの slug（スラッグ）は、ファイル作成コマンドにオプションをつけることで自由に設定することができます。（基本的にはつけといた方が管理しやすそう）

例えばこちらの記事の場合だと以下のように slug を指定してファイルを生成しました。

$ npx zenn new:article --slug zenn-article-setup-local
# => articles/zenn-article-setup-local.md`が作成される

またこれにより以下の URL でこちらの記事にアクセスできるようになります。

https://zenn.dev/ユーザー名/articles/zenn-article-setup-local

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

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

ここから本文を書く

これを見て分かる通り、ファイル先頭部分に---に挟まれる形で予め記事の設定が記載されています。

ここに記事のタイトル（title）やトピックス（topics）などを指定することになります。

あと特徴的なものは絵文字ですね。この絵文字を設定できるのが Zenn のいいところですよね〜つい読みたくなっちゃいますしね。

次に本文部分ですが、基本的には markdown 記法で書いていきます。具体的な書き方については以下の記事を参照してください。

記事のプレビュー

本文がどのように反映されるのか？を確認したい場合は、以下のコマンドによりブラウザで確認できます。

$ npx zenn preview # プレビュー開始
👀 Preview: http://localhost:8000 # デフォルトでは8000番ポート

これにより各記事を執筆しながらプレビューすることができます。

ここまでの作業が一旦終わったら記事をコミットしてリモートリポジトリにプッシュしてみましょう。

published: falseのままなら下書きとして Zenn 側に保存されているはずです。

4. 記事を公開する

では最後に書いた記事を Zenn 側に公開していきましょう。

公開する際は---で囲まれている部分のpublishedオプションをtrueにした上で、ファイルをコミットして、プッシュしましょう。

すると Zenn 側にて同期（デプロイ）が開始されます。

なおデプロイ状況はヘッダーのアイコンにより確認可能です。

またデプロイ履歴に関しても、ダッシュボード上の「デプロイ履歴」タブにていつでも確認可能になっています。

デプロイが終了したのを確認したら、無事記事が公開されているはずです。

うまく行かない場合などがありましたら、以下の記事などを参照しながら解決策を考えてみることをおすすめします。

おわりに

ひとまずこれで最低限の執筆環境は整った気がします。

あとはtextlintやprettierなどのツール類を入れたり、GitHub Actions と連携させてみたりして 「俺の考える最強の Zenn 執筆環境」 を時間をかけて作り上げていきたいですね。

そーいえば最近 Qiita も似たようなツールを出したみたいで...

せっかく Zenn に乗り換えようと画策していたのに、はやくも心が揺らぎそう...笑