Markdownで書いた記事をHTMLとして表示する

COLUMNSの記事本文をMarkdownで保存し、PHPでHTMLへ変換してブラウザに表示する仕組みを作ります。

🎯 目的

021では、自作CMSで公開した記事を COLUMNSとして一般公開できるようにしました。

今回は記事本文をMarkdownで書き、 PHPでHTMLへ変換して表示できるようにします。

CMSでは書きやすいMarkdownを保存し、 公開ページでは見出し・太字・引用・リスト・リンクとして ブラウザに表示する仕組みを作ります。

今回やること

  1. 記事本文をMarkdownとして保存する
  2. markdown.phpに変換処理をまとめる
  3. MarkdownをHTMLへ変換する
  4. column-detail.phpから変換処理を使う
  5. 入力されたHTMLはそのまま実行しないようにする
CMSでMarkdownを書く
↓
MariaDBへ保存
↓
PHPで本文を取得
↓
renderMarkdown()
↓
HTMLへ変換
↓
ブラウザに表示

STEP 1|Markdownで記事を書く

COLUMNSの記事本文は、 CMSのtextareaから入力します。

本文にはHTMLを直接書くのではなく、 Markdownの記号を使います。

## 見出し

### 小見出し

**太字**

> 引用

- リスト

[リンク](https://example.com)
📘 Markdownを読む

## = 見出しです。HTMLのh2へ変換します。
### = 小見出しです。HTMLのh3へ変換します。
**文字** = 太字です。strongへ変換します。
> = 引用です。blockquoteへ変換します。
- = リスト項目です。liへ変換します。
[文字](URL) = リンクへ変換します。

→ 記事を書く人はHTMLタグを直接書かなくても、 記号を使って文章の構造を指定できます。

STEP 2|markdown.phpに変換処理を作る

MarkdownをHTMLへ変換する処理は、 markdown.phpへまとめました。

function renderMarkdown(string $markdown): string
{
    $safe = htmlspecialchars(
        $markdown,
        ENT_QUOTES,
        'UTF-8'
    );

    // MarkdownをHTMLへ変換する処理

    return $html;
}
📘 PHPを読む

function = 関数を定義します。
renderMarkdown = 今回作った関数の名前です。
string $markdown = Markdownの文字列を受け取ります。
: string = 戻り値が文字列であることを表します。
return = 処理した結果を呼び出し元へ返します。

→ Markdownを受け取り、 HTMLへ変換した文字列を返す関数です。
📘 関数に分ける理由

Markdown変換をcolumn-detail.phpへ直接すべて書くのではなく、 markdown.phpへ分けました。

→ 「記事を表示する処理」と 「Markdownを変換する処理」を分けて考えられます。

STEP 3|HTMLを先にエスケープする

Markdownを変換する前に、 入力された文字列を htmlspecialchars()でエスケープします。

$safe = htmlspecialchars(
    $markdown,
    ENT_QUOTES,
    'UTF-8'
);
📘 htmlspecialchars()を読む

htmlspecialchars() = HTMLとして特別な意味を持つ文字を変換するPHPの関数です。

$markdown = 変換する元の文章です。
ENT_QUOTES = シングルクォートとダブルクォートも変換対象にします。
'UTF-8' = 文字コードをUTF-8として扱います。

→ 入力されたHTMLタグを、そのままHTMLとして実行させないようにします。
<script>...</script>
📘 先に安全な文字列へする

入力された文章を最初にエスケープし、 そのあとで自分たちが対応すると決めたMarkdownだけを HTMLへ変換します。

→ 「入力されたHTMLをそのまま許可する」のではなく、 「許可したMarkdown表現だけをHTMLにする」 という考え方です。

STEP 4|行ごとにMarkdownを判定する

本文を行ごとに分け、 行の先頭にある記号を見てHTMLへ変換します。

$lines = preg_split('/\R/u', $safe);

foreach ($lines as $line) {
    // 1行ずつ判定する
}
📘 PHPを読む

preg_split() = 正規表現を使って文字列を分割します。
$lines = 分割した行を保存します。
foreach = 複数のデータを1つずつ順番に処理します。
$line = 現在処理している1行です。

→ 記事本文を行単位に分けて、 1行ずつ「見出しか、引用か、リストか」などを判断します。
📘 /u について

今回のコードでは /uを付けています。

これは正規表現で入力文字列を UTF-8として扱うための指定です。

なぜこれが必要になったのかは、 次の記事で実際に起きた日本語表示のトラブルと一緒に整理します。

STEP 5|MarkdownをHTMLへ変換する

行の内容に応じて、 対応するHTMLタグへ変換します。

if (str_starts_with($line, '### ')) {
    $html[] = '<h3>' . substr($line, 4) . '</h3>';

} elseif (str_starts_with($line, '## ')) {
    $html[] = '<h2>' . substr($line, 3) . '</h2>';

} elseif (str_starts_with($line, '&gt; ')) {
    $html[] = '<blockquote>'
            . substr($line, 5)
            . '</blockquote>';

} else {
    $html[] = '<p>' . $line . '</p>';
}
📘 条件分岐を読む

str_starts_with() = 文字列が指定した文字から始まっているか確認します。
if = 条件が成立した場合の処理です。
elseif = 前の条件が成立しなかった場合に、別の条件を確認します。
else = どの条件にも当てはまらなかった場合です。

→ 行の先頭を見て、 どのHTMLタグへ変換するかを決めています。
📘 変換の考え方

### → <h3>
## → <h2>
> → <blockquote>
通常の文章 → <p>

→ Markdownの記号を読み取り、 ブラウザが理解できるHTMLへ置き換えています。

STEP 6|個別記事からrenderMarkdown()を使う

COLUMNSの個別ページでは、 Markdown変換用のファイルを読み込みます。

require_once __DIR__ . '/markdown.php';
📘 require_onceを読む

require_once = PHPファイルを1回だけ読み込みます。
__DIR__ = 現在のPHPファイルがあるディレクトリを表します。
/markdown.php = 読み込むファイルです。

→ column-detail.phpから markdown.phpの関数を利用できるようにします。

DBから取得した本文は、 次のように表示します。

<?= renderMarkdown($article['body']) ?>
📘 コード全体の意味

$article['body']
→ MariaDBから取得した記事本文です。

renderMarkdown(...)
→ Markdown本文をHTMLへ変換します。

<?= ... ?>
→ 変換結果をHTMLへ出力します。

→ DBのMarkdown本文が、 見出しや太字などを持った記事としてブラウザに表示されます。

📘 021と022のつながり

021
CMSでpublishedになった記事を、 COLUMNSの一覧・個別ページへ表示できるようにしました。

022
その記事本文をMarkdownで書き、 公開時にHTMLへ変換できるようにしました。

→ 021で「記事を公開する道」を作り、 022で「公開された本文を読みやすく表示する仕組み」を追加しました。

📘 処理の流れを読む

入力: CMSのtextareaへMarkdownで記事を書く
↓
保存: Markdownの本文をMariaDBへ保存する
↓
取得: column-detail.phpが記事本文を取得する
↓
処理: renderMarkdown()が安全な文字列へ変換し、 対応しているMarkdownをHTMLへ変換する
↓
出力: 見出し・太字・引用・リスト・リンクなどを ブラウザへ表示する

→ 「Markdownを入力 → DBへ保存 → PHPで変換 → HTMLとして出力」 という流れです。

📝 今回の忘備録

CMSの記事本文はMarkdownのまま保存し、 公開するときにPHPでHTMLへ変換する。

HTMLを直接許可するのではなく、 最初にhtmlspecialchars()でエスケープしてから、 対応すると決めたMarkdownだけをHTMLへ変換する。

Markdown変換処理をmarkdown.phpへ分けることで、 column-detail.phpは記事表示、 markdown.phpは本文変換という役割に分けられる。

今回対応したのは h2・h3・太字・引用・リスト・http/httpsリンク・通常の文章。 必要な機能だけを実装した。

Markdownの行分割では preg_split('/\R/u', $safe) を使用している。 この/uが必要になった理由は次の記事で整理する。

この先やること

タグ: PHP / Markdown / HTML / htmlspecialchars / preg_split / 正規表現 / UTF-8 / CMS / COLUMNS