こんにちはこんにちは！ エンジニア川端です。
プログラマのみなさん。
プログラミング、好きですか？
もちろん好きですよね。
ドキュメント作るの、好きですか？
ふがふがんがぐぐ
そういう気持ちを知ってか知らずか、GitHub の仕組みはよくできてますね。
- Markdown や POD 形式など、色々なマークアップ言語に対応してたり
- マークアップ言語で記述したファイルを置くだけで、こぎれいな HTML として表示してくれたり
- GitHub Pages では「Jekyll」がサポートされてたり
今日は、GitHub 以外のサーバで同じような環境を手軽に用意する方法をお届けします。
やりたいこと
Apache の特定のディレクトリに Markdown 形式で記述したファイルを設置するだけで、HTML で表示してくれる環境を用意する
http://example.jp/markdown/readme.md
にアクセスすると、
ではなく
と表示される
結論から書く
- markdown.php をダウンロードして、markdown/ 以下に設置
- .htaccess 作成して、markdown/ 以下に設置
AddType text/markdown md Action text/markdown /markdown/md.php
- md.php 作成して、markdown/ 以下に設置
<?php require_once 'markdown.php'; if ( isset($_SERVER['PATH_TRANSLATED']) ) { $file = realpath($_SERVER['PATH_TRANSLATED']); $ext = substr($file, strrpos($file, '.') + 1); } if ( $file and is_readable($file) and $ext === 'md') $body = Markdown(file_get_contents($file)); else $body = '<p>cannot read file</p>'; header('Content-Type: text/html;'); echo '<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>Markdown Test</title> </head> <body> ' . $body . ' </body> </html> ';
以上！
あとは、markdown/ 以下に拡張子 .md のファイルをおいてアクセスするだけです。
ローカル環境で自分しか使わないので、細かいことは気にしない。
軽く説明
- readme.md にアクセス
- 拡張子 md のファイルは、コンテントタイプ text/markdown にマップする
AddType text/markdown md
- コンテントタイプ text/markdown の場合、md.php を実行する
Action text/markdown /markdown/md.php
- md.php は、環境変数 PATH_INFO / PATH_TRANSLATED を元にreadme.md を取得し、markdown.php で html 化する
Apache の Action ディレクティブと環境変数 PATH_TRANSLATED の組み合わせでお手軽に実現してみました。
- 英語/日本語など、多言語対応
- Markdown 以外のいろんな書式に対応
- 拡張子だけじゃなく他の制限も
- 拡張子 md なのがイヤ
- カテゴリ分けしたい
- タグつけたい
- 検索したい
などなど色々やりたいことが出てきたら、アプリ導入や開発を検討すればよいかなと。
ドキュメントを作るのが嫌いなわけではなくて、ドキュメントを作るのに時間をかけたくないだけ、というエンジニアはたくさんいると思います。
その数推定 1,000 万人。
そういう方向けに「こんなこともできますよ」という一つのケースとしてお届けしました。お役に立てれば幸いです。
関連記事
