こんにちは、全力開発部の @konoka-iori です。

今回も、「全力開発ブログの作り方」シリーズの記事です。

このシリーズでは、

  • メンバーがどのようにして全力開発ブログに記事を投稿しているか
  • 記事を投稿するにあたって、守るべきルールやコーディング規約にはどんなものがあるのか
  • 全力開発ブログのリポジトリの構成や運用方法はどのようなものか
  • 全力開発ブログのカスタマイズについて

など、全力開発ブログの裏側についてご紹介いたします。

今回の記事では、全力開発ブログに記事が投稿されるまでの流れをご紹介いたします。

以前の記事では、textlintとMarkdownlintの導入や、リポジトリの運用などについてご紹介しました。ぜひこちらもご覧ください。

全力開発ブログの作り方：textlintとMarkdownlintで品質を維持する - 全力開発ブログ

全力開発ブログの作り方：リポジトリの運用 - 全力開発ブログ

Issueで記事の申請を行う

メンバーが新しい記事を追加したいときや、既存の記事を変更・削除したいときは、まず記事のリポジトリにIssueを作成します。

各種申請に対応したIssueフォームを追加しており、これを利用することによって必要な情報を簡単かつ漏れなく記入できます。

Issueフォームは、以下のような内容になっています。

項目 記載内容 必須/任意 入力形式
記事のタイトル 記事のタイトルを記入 必須 テキスト
記事の概要 記事の概要を記入 必須 テキスト
URL（slug） 記事のURLを記入 必須 テキスト
カテゴリー カテゴリーを選択 必須 ドロップダウン（単一選択）
その他のカテゴリー 上記のカテゴリーに含まれない場合記入 任意 テキスト
タグ タグを選択 必須 チェックボックス（複数選択可）
その他のタグ 上記のタグに含まれない場合記入 任意 テキスト

例として、以下の記事を書いたときのIssue内容をご紹介します。

WSL内でDev Container使おうとしたら沼った話 - 全力開発ブログ

Issue内容
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

### 記事のタイトル

WSL内でDev Container使おうとしたら沼った話

### 記事の概要

WSL内でDev Containerを使った開発環境構築をしようとしたらGitHubにログインできてなかったり、
DockerがなぜかWindows側で立ち上がろうとしたりいろいろあったのでその話

- [ ] なにが起こっていたのか
- [ ] 仮説
- [ ] やったこと
- [ ] 結論（どうやって解決したか。ghコマンドとDev Container設定）
- [ ] まとめ

### URL

troubleshooting-wsl-dev-container

### カテゴリ

Tech

### その他のカテゴリ

_No response_

### タグ

Dev Container, Docker, VS Code, Windows

### その他のタグ

WSL2

記事の概要に目次をチェックボックス形式で書いておいて、進捗リストとして使うことがよくあります。

Note
全力開発ブログは zenn.dev をパクって参考にしてカテゴリー分けしています。 全力開発ブログにどんなカテゴリーが設定されているは こちら をご覧ください。

Issueフォームを投稿すると、自動的に以下の要素が付与されます。

  • 投稿者（執筆者）のGitHubアカウントをアサイン
  • new post ラベルを付与
  • Contents of blog.zenryoku.dev のプロジェクトカードを付与

申請内容をレビューする

Issueが作成されると、リポジトリの管理者がIssue内容を確認し、問題がなければ記事の作成を許可します。

新しい記事を申請するIssueには自動的に「new post」のラベルが付与されていますので、必要に応じてフィルタリングして確認できます。

管理者はIssueの内容を確認し、

  • 必要事項がすべて記入されているか
  • 記事のテーマや内容に問題はないか

などを確認します。 もし、記入漏れや不備があれば、Issueのコメントで指摘を行い、修正を依頼します。

Note

申請Issueのコメント欄でよくあるのが、URL（slug）の相談です。 URLは記事のパーマリンクになるため、必須項目としているのですが、申請時に決めかねて一度Issueを投稿して相談するというケースがよくあります。

最近ではChatGPTにIssue内容を投げてURLの候補を提案してもらう方法をとっているのですが、APIとGitHub Actionsを使って自動化することも検討しています。

Issue内容を解析して、URLが記載されてなかったらコメントで候補を提案する仕組みを作ればある程度緩和できるのかなと考えています。

記載内容に問題なければ、管理者は編集者をアサインしたあと「approved」のラベルを付与し、プロジェクトカードのステータスを「執筆開始待ち」にします。

GitHub Actionsでメタデータを自動生成する

Hugoでは、記事のメタデータをYAML形式で記述します。

先ほど例 でいくと、以下のようなメタデータを記述しています。

posts/troubleshooting-wsl-dev-container/index.md
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

---
title: "WSL内でDev Container使おうとしたら沼った話"
date: 2025-01-16T23:10:00+09:00
author: "konoka-iori"
categories:
  - Tech
tags:
  - Dev Container
  - Docker
  - VS Code
  - Windows
  - WSL2
draft: false
---

ただ、このメタデータを手動で記述するのは面倒ですし、間違いや表記揺れも起こりやすいポイントです。

そこで、GitHub Actionsを使って自動生成することによってある種CMSのような使い勝手を実現しています。

さきほど申請内容のレビューが完了すると、「approved」のラベルが付与されるとご紹介しました。

これをトリガーにGitHub Actionsが以下の作業を自動で行います。

  1. 作業ブランチ add/(記事のURL) を作成
  2. 作業ブランチに posts/(記事のURL)/index.md を作成
  3. index.md にIssueの内容に応じたメタデータを生成して書き込む（上記のようなものを自動で作る）
  4. コミットして作業ブランチをプッシュ

Issueフォームによって、記事の申請フォーマットは統一されているので、JavaScriptでIssueの内容をパースして必要な情報を取り出し、メタデータを生成できます。

記事を執筆する

記事が承認され、メタデータが自動生成されたら、さっそく記事の執筆に取り掛かります。

執筆者はIssueのプロジェクトカードを「執筆中」にセットし、作業ブランチをチェックアウトして作業を始めます。

全力開発ブログでの執筆作業は基本的にVS CodeのDev Container環境で行うことを推奨しており、リポジトリをコンテナーボリュームにクローンすることで、.devcontainer/devcontainer.json によって自動的にブログの執筆環境が構築されます。

Tip

Dev Container環境では、textlintやMarkdownlintなどの静的解析ツールが自動で実行されるため、執筆中に誤字脱字や表記揺れ、Markdownの記法ミスなどを検知しやすくなっています。

また、Hugoのショートコードをスニペットとして登録してあるので、記事内でショートコードを使う際にも便利です。

記事投稿時点で全力開発ブログに実装されているショートコードは以下の通りです。

ショートコード 説明
< blog-card "<>" > カード形式でリンクを表示するショートコード
< alert note > 補足情報を示すアラート
< alert tip > ヒントを示すアラート
< alert important > 重要な情報を示すアラート
< alert warning > 警告を示すアラート
< alert caution > 特段の注意を示すアラート
< github-code "<>" > GitHubからコードを取得し、記事中に挿入するショートコード
``` {name=""} コードブロックの言語指定とファイル名を指定できるショートコード

ほかにも、品質維持のために執筆時にはさまざまな基準やアドバイスが設けられています。

それらはすべて 執筆にあたって.md のドキュメントに集約されており、執筆時に気をつけるべきこととして、

  • メタデータの書き方
  • 記事のタイトルの書き方
  • 見出しの書き方
  • 本文の書き方
    • Markdownの基本構文
    • 独自のスタイル設定（Hugoのショートコード）
  • 画像/動画の挿入方法

などが記載されています。

記事の内容をレビューする

記事が完成したら、mainブランチにプルリクエストを作成してレビューを依頼します。

全力開発ブログでは、WordPressで運用していた前身のサイトから引き継いだ記事の採用基準（公開時のチェックリスト）をもとに、レビューを行っています。

リポジトリにプルリクエストのテンプレートを用意し、プルリクエストにレビュー時のチェックリストが記載されるようになっています。

チェックリストの主な内容としては、

  • 該当するIssueをリンクしたか
  • 担当の編集者（レビュアー）をアサインしたか
  • CODEOWNERSに執筆者、およびレビュアーを追加したか

などGitHub上での設定を確認する項目に加えて、執筆者用とレビュアー用の内容チェックリストがそれぞれ含まれています。

アサインされたレビュアーはまず、プロジェクトカードを「レビュー中」にセットし、プルリクエストをチェックアウトして記事の内容を確認します。

レビューでは記事の内容だけでなく、表記揺れや誤字脱字、Markdownの記法ミスなどもチェックします。

また、レビュー時にもGitHub Actionsによる自動チェックも行っています。 記事投稿時点では、

チェック項目 導入意図
記事内のリンクは有効なものか 記事投稿時点ですでに無効になっているリンクがあれば指摘するため。
textlintに準拠しているか 誤字脱字や表記揺れを防ぎ、記事の品質を保つため。
Markdownlintに準拠しているか Markdownの記法ミスを防ぎ、記事の可読性を向上させるため。
画像の形式はAVIFか 画像の表示速度を向上させ、読者の体験を改善するため。

をチェックするGitHub Actionsを設定しています。

全力開発ブログでは表示を高速化するために最新の画像形式であるAVIFを採用しており、GitHub Actionsによる自動チェックで画像が有効なAVIF形式であるかどうかをチェックしています。

Note

現時点では自動で行われるのはチェックまでで、指摘する作業は手動で行っています。 将来的にはreviewdogなどを使ってレビュー工数を削減できないか模索していく予定です。

また進展があれば都度記事にしようと思います。

チェックが完了して、問題がなければそのままmainブランチにマージして完了となります。（プロジェクトカードも自動で「完了」にセットされます）

もし問題があればレビュアーはレビューコメントを残し、執筆者は指摘箇所を修正して再度レビューを依頼します。（完了するまでこれの繰り返し）

これ以降の流れ

レビューが完了したら、mainブランチにマージされて執筆作業完了となります。

ただ、現状mainブランチにマージされてもすぐに記事は公開されません。

全力開発ブログの作り方：リポジトリの運用 - 全力開発ブログ

上記記事で課題として取り上げているのですが、現在の全力開発ブログの運用では、mainブランチにマージされた記事は公開されるまでに手動での同期作業が必要です。

これ以降は管理者側の作業となるため、執筆者は記事の執筆作業が完了した段階で自分の役割は終了となります。

課題と今後の展望

煩雑な作業が必要だったWordPress時代に比べて、ワークフローがGitHubに最適化されてかなりスムーズになったと思います。

しかし、まだまだ改善・効率化の余地はあります。

  • 記事のURLを提案するGitHub Actionsの導入検討
  • レビュー工数を削減するreviewdogの導入検討
  • mainブランチにマージされた記事の自動公開
  • textlintのルールをより充実させる
  • AIによる校正提案ツールの導入検討
  • 読者からのフィードバック収集

など、自動化や効率化を進めていくことで、執筆者やレビュアーの負担をさらに軽減し、より品質の高い記事を提供できるようにしていきたいと考えています。

まとめ

全力開発ブログの記事が公開されるまでの流れをご紹介しました。

これから個人/チーム問わずブログを運用したいと考えている方はもちろん、すでにブログ運用している方の参考にもなれば幸いです。

それから、課題や改善したいことが多すぎるので、別途記事を書きたいと思いました。 （ここですべて語ってしまうと超大作記事になってしまいます。内容も一部他記事と被ってしまいますし）