Zenn
📚

2025-03-23 Zenn-Docsへのドキュメント集約

2025/03/23に公開
GitHub Actions
zenndocs
ドキュメント集約
idea

Zenn-Docsへのドキュメント集約

はじめに

昨日はDiary-Converterのリポジトリ整理を行いました。今日は、各リポジトリのドキュメントをZenn-Docsに集約するという、少し大掛かりなテーマに取り組みます。

背景と目的

これまで、開発日記やプロジェクトに関するドキュメントが複数のリポジトリに分散していました。これでは管理が煩雑になり、必要な情報を見つけるのに時間がかかってしまいます。そこで、Zenn-Docsを中心的なドキュメントリポジトリとして、情報を一元管理することにしました。

具体的には、以下の目的を達成したいと考えています。

  • Zenn-Docsに開発日記とリポジトリを横断するテーマのドキュメント（例えばAuto-logging-Guide）を集約する
  • 各リポジトリから、プロジェクト固有でないドキュメントをZenn-Docsに移動する
  • 開発日記のZenn公開用日記への変換をZenn-Docsのパイプラインに移管する

検討内容

課題の整理

今回のドキュメント集約にあたり、以下の課題があると考えました。

  1. どのドキュメントをZenn-Docsに集約すべきかの判断基準が曖昧
  2. 既存のCI/CDパイプラインの修正が必要
  3. Zenn-DocsのGitHub Actionsワークフローの設計

解決アプローチ

これらの課題を解決するために、以下のアプローチを検討しました。

  1. ドキュメントの分類: プロジェクト固有のドキュメントと、リポジトリを横断する共通ドキュメントに分類する。共通ドキュメントをZenn-Docsに集約する。
  2. CI/CDパイプラインの移行: SiteWatcherのCI/CDパイプラインから開発日記の変換処理を削除し、Zenn-Docsのパイプラインに移行する。
  3. GitHub Actionsワークフローの設計: Zenn-Docsリポジトリに新しいGitHub Actionsワークフローを作成し、開発日記の変更を検知して自動的に変換・公開する。

実装内容

変更点1: Diary-Converterリポジトリのドキュメント移動

Diary-Converterリポジトリから、プロジェクトログをZenn-Docsのdev-recordsに移動しました。また、CI/CD関連のドキュメントもZenn-Docsに移動しました。

変更点2: SiteWatcherリポジトリのドキュメント確認

当初、SiteWatcherリポジトリからもドキュメントを移動しましたが、プロジェクト固有のドキュメントだったため、元の場所に戻しました。

変更点3: CI/CDパイプラインの移行

SiteWatcherのCI/CDパイプラインから開発日記の変換処理を削除し、Zenn-Docsリポジトリに新しいGitHub Actionsワークフローを作成しました。

# .github/workflows/diary-convert.yml
name: Diary Convert

on:
  push:
    paths:
      - 'dev-records/**'

jobs:
  convert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 2 # 変更を検出するために必要

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install dependencies
        run: npm install zenn-cli

      - name: Find latest updated diary file
        id: find_diary
        run: |
          NEWEST_FILE=$(git log -1 --name-only --pretty="format:" | grep ".md$" | head -n 1)
          echo "::set-output name=file::$NEWEST_FILE"

      - name: Convert diary to Zenn article
        run: |
          FILENAME="${{ steps.find_diary.outputs.file }}"
          BASE_FILENAME=$(basename "$FILENAME" .md)
          # Zennのslugルールに合わせてファイル名を変換
          SLUG=$(echo "$BASE_FILENAME" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9-]+/g' | sed -E 's/^-+//' | sed -E 's/-+$//')
          # 日本語が含まれる場合はローマ字に変換（例: こんにちは -> konnichiha）
          # SLUG=$(echo "$SLUG" | sed -E 's/こんにちは/konnichiha/g' | sed -E 's/こんばんは/konbanha/g' | sed -E 's/おはよう/ohayou/g')
          # 文字数制限（50文字）
          SLUG=$(echo "$SLUG" | cut -c -50)
          echo "slug: $SLUG"
          npx zenn new:article --slug "$SLUG" --type "tech" --title "$BASE_FILENAME"
          cp "$FILENAME" articles/"$SLUG".md
          # 記事の先頭にfrontmatterを追加
          echo "---" >> articles/"$SLUG".md
          echo "title: \"$BASE_FILENAME\"" >> articles/"$SLUG".md
          echo "emoji: \"📝\"" >> articles/"$SLUG".md
          echo "type: \"tech\"" >> articles/"$SLUG".md
          echo "topics: [\"開発日記\"]" >> articles/"$SLUG".md
          echo "published: false" >> articles/"$SLUG".md
          echo "---" >> articles/"$SLUG".md
          # 記事の末尾に自動生成メッセージを追加
          echo ":::message\nこの記事はGitHub Actionsによって自動生成されています。\n:::" >> articles/"$SLUG".md

      - name: Commit and push changes
        run: |
          git config --global user.email "actions@github.com"
          git config --global user.name "GitHub Actions"
          git add articles/*
          git commit -m "Add new Zenn article from diary" || echo "No changes to commit"
          git push origin main || echo "No changes to push"

変更点4: ワークフローの改善

GitHub Actionsのワークフローをシンプルにし、Zenn固有の制約処理を外部ファイルに分離しました。また、開発日記のファイル名をyyyy-mm-dd-development.md形式に統一することで、変換処理が不要になりました。

# tools/diary-filename-processor.sh
#!/bin/bash

FILENAME="$1"
BASE_FILENAME=$(basename "$FILENAME" .md)
SLUG=$(echo "$BASE_FILENAME" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9-]+/-/g' | sed -E 's/^-+//' | sed -E 's/-+$//' | cut -c -50)

echo "$SLUG"

変更点5: SiteWatcherのCI/CDパイプライン修正

SiteWatcherのCI/CDパイプラインから開発日記の変換処理を完全に削除しました。

変更点6: 命名規則の明文化

開発日記ファイルの命名規則をyyyy-mm-dd-development.md形式に統一し、Auto_Logging_Guide.mdに明記しました。

技術的なポイント

今回の実装で特に重要だったのは、GitHub Actionsのワークフロー設計です。変更を検知して自動的に変換・公開する処理を、シンプルかつ効率的に実現する必要がありました。また、Zennのslugルールに合わせたファイル名の変換処理も、重要なポイントでした。

所感

今回のドキュメント集約作業は、予想以上に手間がかかりました。特に、どのドキュメントをZenn-Docsに集約すべきかの判断に迷いました。しかし、最終的には、情報を一元管理することで、開発効率が向上すると確信しています。

また、GitHub Actionsのワークフロー設計は、試行錯誤の連続でした。しかし、自動化されたパイプラインが完成したときの達成感は格別でした。

今後の課題

今後の課題としては、以下の点が挙げられます。

  1. Zenn-Docsのドキュメント構成の最適化
  2. GitHub Actionsワークフローのさらなる改善
  3. ドキュメントの自動生成ツールの導入

まとめ

今回の開発では、各リポジトリのドキュメントをZenn-Docsに集約し、情報の一元管理を実現しました。また、GitHub Actionsを活用した自動化パイプラインを構築し、開発効率の向上を図りました。今後は、これらの成果を活かし、より効率的な開発体制を構築していきたいと思います。

GitHubで編集を提案

Discussion