Zenn
📝

Zenn公開用日記のフォーマット最適化 : [Docs] 開発日記 #1

に公開
Zenn
GitHub Actions
開発日記
tech

関連リンク

Zenn公開用日記のフォーマット最適化

はじめに

昨日は各リポジトリのドキュメントをZenn-Docsに集約しました。今日は、その流れでZenn公開用日記のフォーマットを最適化し、より読みやすく、プロジェクト間の関連性が明確になるように改善を進めていきます。

背景と目的

開発日記をZenn記事として公開するにあたり、より洗練されたフォーマットが必要だと感じました。特に、プロジェクト間の関連性を明確にし、読者がプロジェクトの全体像を把握しやすくすることを目指します。また、日記の自動生成ツールであるdiary-converterとの連携を強化し、より効率的な開発ワークフローを構築することも目的としています。

検討内容

課題の整理

現在のZenn公開用日記のフォーマットには、以下の課題があります。

  1. 関連リポジトリへのリンク不足: 記事から関連する開発プロジェクトへのアクセスが容易でない。
  2. 前日の開発日記へのリンク不足: 過去の文脈を追いにくい。
  3. Zenn記事タイトルのスタイル統一性の欠如: 日付ベースのタイトルでは、プロジェクトの連番管理が難しい。

解決アプローチ

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

  1. Zenn記事テンプレートの修正: 関連リンクセクションを追加し、プロジェクトリポジトリと前日の開発日記へのリンクを明示的に表示する。
  2. diary-converterの修正: 新しいテンプレートに対応し、タイトルの自動生成、関連リンクの自動挿入、プロジェクト名と連番の管理機能を追加する。
  3. GitHub Actionsワークフローの改善: 変換後の記事を自動的に修正し、プロジェクト名と連番を自動的に設定する機能を追加する。

実装内容

変更点1: Zenn記事テンプレートの修正

Zenn記事のテンプレートファイル（dev-docs/zenn_template.md）を修正し、以下の変更を加えました。

  • タイトルのスタイルを「[プロジェクト名] 開発日記 #[連番]: [テーマ]」形式に変更
  • 関連リンクセクションを追加（プロジェクトリポジトリと前回の開発日記へのリンク）
  • typeをtechに変更し、topicsのデフォルト値に開発日記を追加

変更点2: diary-converterとの互換性を確保するための暫定対応

diary-converterツールとの互換性を確保するため、テンプレートにコメントを追加し、実際のタイトルフォーマットを明記しました。また、関連リンクセクションにもコメントを追加し、手動で情報を追加する必要があることを説明しました。

変更点3: diary-converterツールの修正案の作成

diary-converterツールの修正案を作成し、以下の機能を追加しました。

  • 新しいパラメータ（プロジェクト名、連番、前回の記事スラッグ）の追加
  • frontmatterテンプレートの修正
  • 関連リンクセクションの自動生成機能の追加
  • プロンプトの修正
  • コマンドライン引数の追加
# diary_converter.pyの修正案

# 1. 新しいパラメータの追加
def __init__(self, model="gemini-2.0-flash-001", template_path="./templates/zenn_template.md", 
             debug=False, project_name=None, issue_number=None, prev_article_slug=None):
    """初期化"""
    self.model_name = model
    self.template_path = template_path
    self.debug = debug
    self.project_name = project_name  # プロジェクト名
    self.issue_number = issue_number  # 連番（Issue番号）
    self.prev_article_slug = prev_article_slug  # 前回の記事スラッグ
    self.setup_api()

# 2. frontmatterテンプレートの修正
frontmatter_template = f"""---
title: "{self.project_name or 'プロジェクト'} 開発日記 #{self.issue_number or '1'}: {theme_name}"
emoji: "{template_fm.get('emoji', '📝')}"
type: "{template_fm.get('type', 'tech')}"
topics: {template_fm.get('topics', ['開発日記', 'プログラミング'])!r}
published: {str(template_fm.get('published', False)).lower()}
---"""

# 3. 関連リンクセクションの生成
repo_link = f"https://github.com/centervil/{self.project_name}" if self.project_name else "https://github.com/centervil/[リポジトリ名]"
prev_article_link = f"https://zenn.dev/centervil/articles/{self.prev_article_slug}" if self.prev_article_slug else "https://zenn.dev/centervil/articles/[前回の記事スラッグ]"

related_links_section = f"""## 関連リンク

- **プロジェクトリポジトリ**: [{self.project_name or 'プロジェクト名'}]({repo_link})
- **前回の開発日記**: [前回のタイトル]({prev_article_link})
"""

# 4. プロンプトの修正
prompt = f"""以下の開発日記を、Zenn公開用の記事に変換してください。

# 入力された開発日記
{content}

# 変換ルール
1. 「会話ログ」セクションは、対話形式ではなく、ストーリー形式に書き直してください
2. 技術的な内容は保持しつつ、読みやすく整理してください
3. 「所感」セクションを充実させ、開発者の視点や感想を追加してください
4. マークダウン形式を維持し、コードブロックなどは適切に整形してください
5. 記事の先頭に以下のfrontmatterを追加してください：

{frontmatter_template}

6. frontmatterの直後に以下のメッセージボックスを追加してください：

{message_box_template}

7. メッセージボックスの直後に以下の関連リンクセクションを追加してください：

{related_links_section}

# テンプレート構造
以下のテンプレート構造に従って記事を作成してください。各セクションの目的と内容を理解し、開発日記の内容に合わせて適切に変換してください：

{template_structure}

# 記述ガイドライン
{guidelines}

# 出力形式
frontmatterを含むマークダウン形式の完全な記事を出力してください。テンプレートの構造に従いつつ、開発日記の内容を適切に反映させてください。
以下の点に注意してください：
1. コードブロックは必要な場合のみ使用し、記事全体をコードブロックで囲まないでください
2. 記事の先頭や末尾に余分なコードブロックマーカー（```）を付けないでください
3. 記事の先頭に```markdownなどの言語指定を付けないでください
"""

# 5. コマンドライン引数の追加
parser.add_argument("--project-name", default="", help="プロジェクト名")
parser.add_argument("--issue-number", default="", help="連番（Issue番号）")
parser.add_argument("--prev-article", default="", help="前回の記事スラッグ")

# 6. GitHub Actionsの入力パラメータの追加
converter = DiaryConverter(
    model=args.model,
    template_path=args.template,
    debug=args.debug,
    project_name=args.project_name,
    issue_number=args.issue_number,
    prev_article_slug=args.prev_article
)

変更点4: GitHub Actionsワークフローファイルの修正案の作成

GitHub Actionsワークフローファイルの修正案を作成し、新しいパラメータを指定するための設定を追加しました。

# diary-convert.ymlの修正案

- name: Run diary-converter
  uses: centervil/Diary-Converter@main
  with:
    source_file: ${{ steps.find-diary.outputs.diary_file }}
    destination_file: ${{ steps.find-diary.outputs.output_file }}
    api_key: ${{ secrets.GOOGLE_API_KEY }}
    model: gemini-2.0-flash-001
    template: dev-docs/zenn_template.md
    debug: 'true'
    project_name: 'Zenn-Docs'  # プロジェクト名を指定
    issue_number: '1'  # 連番を指定（自動的にインクリメントする仕組みも検討）
    prev_article: '2025-03-23-dev-diary'  # 前回の記事スラッグを指定

技術的なポイント

今回の実装で特に重要だったのは、diary-converterツールとの連携です。既存のツールを最大限に活用しつつ、新しいテンプレートに対応するための修正案を作成しました。また、GitHub Actionsワークフローを改善することで、自動化された開発プロセスを実現することを目指しました。

所感

今回の開発を通じて、Zenn記事のフォーマットを改善するだけでなく、開発プロセス全体の効率化についても深く考えることができました。特に、diary-converterツールとの連携は、今後の開発日記の作成を大幅に効率化する可能性を秘めていると感じています。

今後の課題

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

  1. diary-converterツールの修正をPull Requestとして提案し、マージしてもらう。
  2. 連番の自動インクリメント機能の実装。
  3. 前回の記事スラッグの自動取得機能の実装。

まとめ

今回は、Zenn公開用日記のフォーマットを最適化し、より一貫性のある記事が生成されるように改善しました。関連リンクの追加により、プロジェクト間の関連性が明確になり、読者がプロジェクトの全体像を把握しやすくなることを期待しています。今後は、diary-converterツールとの連携を強化し、より効率的な開発ワークフローを構築していきます。

GitHubで編集を提案

Discussion