GitHub Actions Advent Calendar 2024

設計書はMarkdownで管理してPDFに自動変換しよう！

Posted at 2024-12-07

はじめに

皆さんは設計書を何で作成していますか？
Confluence や Notion といったWebサービスが使えたり、wiki を立てられる環境であれば理想的ですが、未だにExcel で管理している現場も多いのではないでしょうか。
本記事では、Excel設計書の代替としてMarkdownによる設計書作成を提案します。

Excel設計書の問題点

Excelでの設計書作成には様々なデメリットがあります。

バージョン管理がしづらい
差分比較がしづらい
検索がしづらい
生成AIを活用した作成がしづらい
印刷レイアウトが崩れやすい

Markdown で設計書を書くことのメリット

Markdown はテキストベースのため、バージョン管理ツールによる管理が容易です。
これにより、過去バージョンとの比較や検索が可能になります。
また、生成AIによる恩恵（作成補助やレビュー等）も多く得ることができます。

デメリットとしては、

ダイアグラムが描きづらい
Excelと比べて閲覧や印刷に一手間かかる

といったものがありますが、

Marmeid　や PlantUML といったテキストベースの作図ツールの活用
PDF や HTML への変換

を行うことで大部分を解消することができます。
詳しくは以下の記事で実践していますので、ご参照ください。

Markdown設計書の管理方法

具体的にMarkdown形式の設計書をどのように管理すれば良いか、1例を紹介したいと思います。

このサンプルでは、Markdown形式の設計書をGitHubで管理し、GitHub Actions によりPDFを自動生成し、GitHub Pages で公開します。

本記事のソースは GitHub に上げてあります。

ディレクトリ構成

designs ディレクトリ内に設計書群を格納します。
本サンプルでは、このディレクトリ内のMarkdownファイルを全てPDFに変換＋公開します。

./ 
├── .github/
│ └── workflows/
│     └── main.yml
├── designs/
│ ├── login.md
│ ├── process.md
│ └── ... # その他のMarkdownファイル
└── README.md

手順

1. Markdownで設計書を書く

まず、設計書をMarkdown形式で記述します。以下はサンプルのMarkdownファイルです。

`login.md` を作成

# システム設計書

## 1. はじめに
本システム設計書は、ネコネコシステムの設計をまとめたものである。

## 2. 機能一覧
- ユーザー管理機能
  - ユーザー登録
  - ログイン/ログアウト
- 猫管理機能
  - 猫情報追加
  - 猫情報編集

## 3. クラス図

```mermaid
classDiagram
class User {
    +String name
    +String email 
    +void login() 
    +void logout()
}
class Cat {
    +String name
    +float power
    +void add()
    +void edit()
} 
User "1" -- "many" Cat : manages
```

`process.md` を作成

# 猫を飼うプロセス

## 1. はじめに
このドキュメントでは、猫を飼うプロセスをシーケンス図で示しています。

## 2. 猫を飼うプロセス

以下は、猫を飼うプロセスを示すシーケンス図です。

```mermaid
sequenceDiagram
    participant 飼い主
    participant 里親募集サイト
    participant 猫
    participant 獣医師

    飼い主->>里親募集サイト: 猫を探す
    里親募集サイト-->>飼い主: 猫の一覧を表示
    飼い主->>飼い主: 猫を選ぶ
    飼い主->>里親募集サイト: 応募する
    里親募集サイト-->>飼い主: 面接日程を調整
    飼い主->>猫: 面接をする
    猫-->>飼い主: 採用
    飼い主->>獣医師: 健康診断を予約
    獣医師-->>飼い主: 健康診断を実施
    飼い主->>飼い主: 猫を迎える準備
    飼い主->>猫: 猫を迎える
    飼い主->>猫: 愛情を注ぐ
    note right of 飼い主: 猫との新しい生活の始まり
```

2. GitHubリポジトリを設定する

新しいリポジトリを作成: GitHubで新しいリポジトリを作成
Markdownファイルを追加: リポジトリに設計書のMarkdownファイルを追加

3. GitHub Actionsを設定する

pandocとMermaidを使用してPDFを生成するGitHub Actionsのワークフローを作成します。
リポジトリのルートに .github/workflows/main.yml ファイルを作成し、以下の内容を記載して下さい。

※ ローカルで変換を試す場合は以下の記事を参照

name: Convert Markdown to PDF

on:
  push:
    branches:
      - main

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Install dependencies
      run: |
        sudo apt-get update
        wget https://github.com/jgm/pandoc/releases/download/3.5/pandoc-3.5-1-amd64.deb
        sudo apt install ./pandoc-3.5-1-amd64.deb
        sudo apt-get install -y texlive-xetex texlive-lang-japanese texlive-luatex
        sudo apt-get install -y npm curl
        npm install -g @mermaid-js/mermaid-cli
        curl -o diagram.lua https://raw.githubusercontent.com/pandoc-ext/diagram/refs/heads/main/_extensions/diagram/diagram.lua

    - name: Generate PDFs
      run: |
        mkdir -p pdfs
        for file in designs/*.md; do
          filename=$(basename -- "$file")
          pdfname="${filename%.md}.pdf"
          pandoc "$file" -o "pdfs/$pdfname" --pdf-engine=lualatex -V documentclass=ltjarticle -V geometry:margin=20mm --lua-filter=diagram.lua
        done

    - name: Move PDFs to docs
      run: |
        mkdir -p docs
        mv pdfs/* docs/

    - name: Generate index.html
      run: |
        echo '<html><body><h1>Generated PDFs</h1><ul>' > docs/index.html
        for pdf in docs/*.pdf; do
          filename=$(basename -- "$pdf")
          echo "<li><a href=\"$filename\">$filename</a></li>" >> docs/index.html
        done
        echo '</ul></body></html>' >> docs/index.html

    - name: Setup Pages
      uses: actions/configure-pages@v5

    - name: Upload Artifacts to GitHub Pages
      uses: actions/upload-pages-artifact@v3
      with:
        path: ./docs

    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4

GitHub Actionsワークフローの各ステップの説明

#	ステップ名	説明
1	uses: actions/checkout@v2	リポジトリのコードをチェックアウトして、ワークフロー内で利用できるようにします。
2	Install dependencies	必要な依存関係をインストールします。Pandoc、TeX Live、Node.js、Mermaid CLI、およびcurlをインストールします。
3	Generate PDFs	designsディレクトリ内のすべてのMarkdownファイルをPDFに変換し、pdfsディレクトリに保存します。
4	Move PDFs to docs	生成されたPDFファイルをdocsディレクトリに移動し、GitHub Pagesで公開するための準備をします。
5	Generate index.html	生成されたPDFファイルへのリンクを含むindex.htmlページを作成します。
6	Setup Pages	GitHub Pagesの設定を行います。
7	Upload Artifacts to GitHub Pages	生成されたPDFファイルとindex.htmlページをGitHub Pagesにアップロードします。
8	Deploy to GitHub Pages	GitHub Pagesにデプロイします。

4. GitHub Pagesを設定する

GitHub Pagesを有効化:
- リポジトリの「Settings」に移動し、「Pages」セクションを表示
- 「Source」ドロップダウンから「GitHub Actions」を選択
GitHub Actionsからの書き込み許可:
- リポジトリの「Settings」に移動し、「Actions」=>「General」セクションを表示
- 「Workflow permissions」の「Read and write permissions」にチェックをいれ、「Save」をクリック