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

# はじめに

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

# Excel設計書の問題点

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

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

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

Markdown はテキストベースのため、バージョン管理ツールによる管理が容易です。
これにより、過去バージョンとの比較や検索が可能になります。
また、生成AIによる恩恵（作成補助やレビュー等）も多く得ることができます。
  
デメリットとしては、
- ダイアグラムが描きづらい
- Excelと比べて閲覧や印刷に一手間かかる

といったものがありますが、
- Marmeid　や PlantUML といったテキストベースの作図ツールの活用
- PDF や HTML への変換

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

https://qiita.com/grhg/items/c76121677d040569a8d9

# Markdown設計書の管理方法

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

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

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

https://github.com/tgrhg/markdown-to-pdf-sample

## ディレクトリ構成

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

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

## 手順

### 1. Markdownで設計書を書く

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

#### `login.md` を作成

````markdown
# システム設計書

## 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リポジトリを設定する

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

### 3. GitHub Actionsを設定する

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

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

https://qiita.com/grhg/items/c76121677d040569a8d9


```yaml
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を設定する

1. **GitHub Pagesを有効化**:
   - リポジトリの「Settings」に移動し、「Pages」セクションを表示
   - 「Source」ドロップダウンから「GitHub Actions」を選択
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294382/23775a2d-8c15-6ccb-0834-ea6dd6c1c8eb.png)

2. **GitHub Actionsからの書き込み許可**:
    - リポジトリの「Settings」に移動し、「Actions」=>「General」セクションを表示
    - 「Workflow permissions」 の 「Read and write permissions」にチェックをいれ、「Save」をクリック
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294382/f648c0e0-05ae-64f8-7c76-bb4cea1fbb3b.png)


### 5. 完了

これで、リポジトリにプッシュするたび GitHub Actionsがトリガーされ、MarkdownファイルからPDFが生成され、GitHub Pagesで公開されます。

https://tgrhg.github.io/markdown-to-pdf-sample/

#### Top page
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294382/ee9abb7d-e5ca-ec63-0836-8967e69c7276.png)

#### `login.pdf`
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294382/e363d922-0021-ff09-5887-e9eb3efbc33f.png)

#### `process.pdf`
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3294382/11d17e4c-ef80-2ca3-deae-7a46dd0ea3ab.png)


### 最後に

この方法を使用することで、設計書の管理と共有が簡単になります。
不確実なドキュメント管理から脱却しましょう！