Zennでテックブログを運用するにあたって決めたルール

こんにちは！ハコベル開発チームの飯盛です。

４月に新卒入社し、現在は荷主と運送会社をつなぐマッチングプラットフォーム、ハコベルカーゴの開発に携わっています。

ハコベルは今月から Zenn でテックブログを開始しました。
立ち上げにあたり、Zenn でテックブログを運用する際のルールやフローを決定したので、もしこれから Zenn を使ってテックブログを始める方の参考になればと思い、それらを共有しようと思います！

フローを決める上で考えたこと

テックブログの運用をする上で、エンジニアが執筆しやすい環境にするというのはとても重要なので、エンジニアが記事本文を書くこと以外の作業をするというのはできるだけ避けたいと思いました。

そのため定型的な作業は可能な限り自動化し、執筆者が記事の内容以外のことで悩まないような工夫をしました。

執筆フロー

1. 記事のマークダウンファイルを作成

はじめに記事のソースとなるファイルを作成します。
Zenn CLI には以下のコマンドが用意されており、これを用いるとマークダウンファイルが自動生成されます

$ npm run zenn new:article

このコマンドで、articles/ランダムなslug.mdというファイルが作成されます。slug（スラッグ）はその記事のユニークな ID のようなものです。

はじめはこのslugをそのまま利用することも考えましたが、ファイル名がランダムな文字列になっている以上はファイルツリー内で複数の記事がランダムに並んでしまいます。そのため記事が増えるにつれて、articles配下の目的のファイルが見つけにくくなってしまいます。

そのためこのコマンドをカスタマイズし、articles/今日の日付-ランダムなslug.mdというファイルが生成されるようなコマンドを作成しました。

zenn-cliがNode.jsに依存しており、環境構築の手順を増やさないためにzxを利用しています。

new-articles.mjs

const path = require("path");
	
// デフォルトで生成されるファイル名(artcles/xxxx.md)を取得
let filePath = (await $`npm run zenn new:article -- --machine-readable | tail -1`).stdout.trim();

// articles/yyyyMMdd-xxxx.mdとなるようファイル名を書き換える
let { dir, base: fileName } = path.parse(filePath);
let date = (await $`date "+%Y%m%d"`).stdout.trim();
let newPath = `${dir}/${date}-${fileName}`;

$`mv ${filePath} ${newPath}`;

このようなファイル名にすることで、作業者が見やすい順にファイルが並んでくれます。

これを実行するコマンド(以下の例だとnpm run new-article)を npm scripts に書いて実行すると、記事が生成されます

package.json

{
  ...
    "scripts": {
    "zenn": "zenn",
    "new-article": "zx ./scripts/new-articls.mjs"
  },
  ...
}

2. 記事のプロパティを設定する

1 のコマンドで記事を作成すると、以下のような設定がデフォルトで書いてあります

---
title: ""
emoji: "👲"
type: "" # tech: 技術記事 / idea: アイデア
topics: []
published: false
---

以下の項目が設定できます。

• title: 記事のタイトル
• emoji: Zenn のトップページや記事のトップに記載する絵文字を指定できます。好みで設定しましょう。
• type: idea かtech を指定できます

  キャリアの話など技術が直接関係しないものは idea, 技術記事は tech にします。詳細はこちらの記事を参考にしてみてください

• topics: twitter のハッシュタグのように自由に設定できます。ハコベルのテックブログではhacobellというタグは含めるようにしています。
• published: ここをtrueにしてmainブランチにpushすると記事が公開されます。
• published_at : 公開日を指定できます。指定したい場合はつけますが、ここに特段ルールは設けていません。

3. 記事本文を書く

お好きなエディタで記事を書きます。
Zenn特有のmarkdown記法などもあるので、以下を参考にしてみてください。
https://zenn.dev/zenn/articles/markdown-guide
npm zenn preview コマンドで記事のプレビューがlocalhost:8000 で立ち上がるので、Zenn上での見え方を確認しながら執筆できます。

公開フロー

1. published: trueにしてPRを作り、レビュー依頼を投げる。

mainブランチにマージされない限りは公開されることはないので、レビュー依頼を投げる段階で公開フラグをtrueにしています。

2. レビュワーは該当ブランチをpullして、ローカルで記事のレビューを行う

※ 以下のZenn Preview for github.devというVSCode拡張を使うとgithub.dev上でプレビューも可能です。

https://marketplace.visualstudio.com/items?itemName=zenn.zenn-preview

3. 通常のPRと同様に、approveされたらmainにマージする。

このタイミングでZennのgithub連携が走り、自動で公開されます。

正常に公開されていれば公開完了です！

まとめ

今回考えたフローにおいては、基本的に執筆者は
記事作成コマンドを叩く → 記事を書く → PRを作る
という作業だけで完結します。

記事のファイル名も自動生成されるため毎回考える必要もありませんし、公開もPRがマージされれば自動で公開されます。
これによりエンジニアは記事の執筆だけに専念できる環境になったと思います。

今後はレビュー項目を充実させたり、誤字脱字がないかCIでチェックする仕組みを導入したりしていきたいと考えています！

最後に

以上、Zennでテックブログを運用する際のルールの紹介でした。
ぜひご参考にしていただければと思います!