PHPを使用したマークダウンファイルの読み込みと整形 の設計 with ChatGPT

• 設計第1フェーズ　全体像
• 設計詳細　ファイルの読み込み
• 設計詳細　データの変換と整形
• 設計詳細　ルーティングとURL設計
• 設計第２フェーズ　全体像
• title,descriptionなどをフロントマターで設定
• 目次(toc)の生成

当サイトの記事コンテンツ(article/配下)はマークダウンで管理しています。

ルーティング処理で動的にマークダウンを読み込んでいます。また、マークダウンファイルはphpの処理でhtmlに変換しています。

これらの設計をChatGPTをアシスタントに設計を考えました。以下はその記録を整理しつつまとめたものです。

設計第1フェーズ　全体像

まずは第1フェーズとして「PHPを使用したマークダウンファイルの読み込みと整形」を必要最小限の機能で実装するための設計を考えました。

以下は設計の全体像です。

1. ファイルの読み込み:

   • ユーザーがアクセスするマークダウンファイルを指定し、PHPでファイルを読み込みます。

2. データの変換と整形:

   • マークダウンファイルから抽出したデータを必要な形式に変換します。たとえば、見出し、段落、リスト、画像などの要素をHTMLに変換します。マークダウンパーサーを使用することが一般的です。PHPにはいくつかの優れたマークダウンパーサーライブラリが存在します（例：Parsedown、CommonMark）。
   • 今回はParsedownを使います。
   • データを必要な形式に整形するために、テンプレートエンジンを使用することもできます。PHPには人気のあるテンプレートエンジンとしてTwigやSmartyなどがあります。
   • 今回はTwigを使います。

3. ルーティングとURL設計:

   • ユーザーがアクセスするURLに基づいて、適切なマークダウンファイルを読み込んでページを生成する必要があります。
   • 一般的な方法として、ルーティングシステムを使用してURLとマークダウンファイルの対応関係を定義します。PHPにはSlim、Laravelなどの人気のあるルーティングライブラリがあります。
   • こんかいはSlimを使います。

それぞれの設計について具体的に説明していきます！

設計詳細　ファイルの読み込み

1. マークダウンファイルの指定:

   • ユーザーがアクセスするマークダウンファイルを指定する方法を検討します。これは、URLパラメータやクエリパラメータ、フォームの送信など、プロジェクトの要件に応じて選択します。

2. ファイルの読み込み:

   • マークダウンファイルを指定した場所から読み込みます。
   • 今回はURLの「article/の一つ下の階層のパス名」を用いて対応するファイルを指定する設計とします。

設計詳細　データの変換と整形

1. マークダウンからHTMLへの変換:

   • Parsedownを使用しマークダウンファイルから抽出したデータをHTML形式に変換します。

2. データの整形:

   • テンプレートエンジンにはTwigを使用しマークダウンからHTMLに変換されたデータを、必要な形式に整形します。これにより、データをテンプレートに埋め込んで最終的な出力を生成します。

3. データの出力:

   • 整形されたデータを出力する方法を検討します。これには、Webページの表示、ファイルの保存、APIのレスポンスなど、プロジェクトの要件に応じた方法を選択します。
   • 今回はシンプルに「Webページの表示」によって出力します。

設計詳細　ルーティングとURL設計

1. ルーティングの定義:

   • ユーザーがアクセスするURLと対応する処理を定義します。これにより、正しいマークダウンファイルを読み込んでページを生成できるようにします。
   • 一般的なルーティングライブラリやフレームワークを使用することが推奨されます。今回はSlimを使用します。

2. URLパターンの設計:

   • ルーティングに使用するURLパターンを設計します。これにより、ユーザーが指定するURLに基づいて対応するマークダウンファイルを特定できます。
   • URLパターンは、正規表現やワイルドカードを使用して柔軟に指定することができます。たとえば、「/pages/{page}」のように、パラメータを含んだパターンを設定することができます。
   • 今回は「/articles/{ページ名}」のような設計にします。

3. ルーティングの処理:

   • ルーティングによって特定された処理を実行します。これには、指定されたURLから必要な情報を抽出し、該当するマークダウンファイルを読み込んでページを生成する処理が含まれます。
   • ルーティング処理では、URLパラメータの取得、必要なマークダウンファイルの読み込み、ページ生成処理の呼び出し、出力の表示などを行います。

4. エラーハンドリング:

   • ルーティングで指定されたURL以外にアクセスがあった場合や、該当するマークダウンファイルが見つからなかった場合などのエラーを適切にハンドリングする必要があります。これにより、適切なエラーページやメッセージを表示できます。

設計第２フェーズ　全体像

フェーズ１「PHPを使用したマークダウンファイルの読み込みと整形」を必要最低限実装する中で「あった方が良い」と気づいた機能をフェーズ2として実装しました。 その設計を以下に記します。

title,descriptionなどをフロントマターで設定

Webページである以上、メタタグのtitleとdescriptionが必要です。他には更新日もあると良いでしょう。 これらは今後記事一覧ページを作成する際にも役立つでしょう。

しかし、上記のようなドキュメント自身の情報（メタ情報）の管理はマークダウンでは困難です。 解決策として「フロントマター」という仕組みを取り入れました。

※フロントマターとは、mdファイルの先頭に以下のようにyaml形式で記述したものです。

---
title: PHPを使用したマークダウンファイルの読み込みと整形 の設計 with ChatGPT
description: ChatGPTをアシスタントに設計を考えた記録（マークダウンファイルを読み込み、データの変換と整形、マークダウンファイルからHTMLへの変換、テンプレートエンジンの利用、ルーティングとURL設計）
created: "2023-07-16"
---

設計は以下の通りです。

1. フロントマターデータの解析:
   • 各.mdファイルからフロントマターデータを抽出します。
   • YAMLパーサや正規表現を使用して、フロントマターデータを解析します。
   • 解析結果として、各ファイルのタイトルや説明などの情報を取得します。

目次(toc)の生成

マークダウンが使えるCMSによくある要素としてtoc(Table of contents)があります。マークダウンの見出しを元に自動で生成される目次です。 設計は以下の通りです。

1. 目次(toc)の生成
   • ToCの項目とHタグは、id属性で関連付けられており、ToCの項目をクリックすると、対応するHタグに移動することができます。
   • HタグにはToCの項目であるaタグのhrefのアンカーリンク先をidとして設定します。
   • マークダウンパーサーはParsedownを使います。
   • テンプレートエンジンはtwigを使います。
   • idの文字列には日本語が設定されることがあります。
   • idの文字列には全角・半角スペースが入ることがあります。