1. Home（グラスタの場所一覧表〜入手範囲別〜）
  2. 個人サイト制作：サイトマップ
  3. GitHubのREADMEをPythonを使ってWebページにする
Fein Atelier - org
Fein Atelier - org

個人サイト制作：サイトマップへ戻る

GitHubのREADMEをPythonを使ってWebページにする

READMEを書く意義は、単なる「説明文」以上のものです。
プロジェクトの顔であり、開発者と利用者をつなぐ最初の接点になります。
コードそのものが機能を語る一方で、READMEはそのコードがどんな背景で生まれ、どんな目的を持ち、どう使われるべきかを物語る場所です。
ここに明快さや温度感があるかどうかで、プロジェクトの印象は大きく変わります。

READMEが整っていると、初めて訪れた人が迷わず環境構築や利用方法に進めます。
逆にREADMEが曖昧だと、せっかくの良いコードも「使いにくい」と判断されてしまうことがあります。
つまり、READMEは技術的なハードルを下げ、参加や利用を促すための入り口なのです。
さらに、READMEは開発者自身にとっても「このプロジェクトは何を目指しているのか」を再確認する場になります。
書く過程で目的や設計思想を整理でき、チーム開発なら共通認識を築く助けにもなります。

また、READMEは単なるマニュアルではなく、プロジェクトの文化や美学を伝える手段でもあります。
シンプルで読みやすい構成にするか、ユーモアを交えて親しみやすくするか、あるいは厳密に技術的なドキュメントとして仕上げるか。
選び方次第で「このプロジェクトはどんな人に向けているのか」が自然と伝わります。

要するに、READMEは「コードを動かすための説明書」であると同時に「プロジェクトの理念を示す看板」でもあり、技術的な利便性と文化的な魅力を両立させる場なのです。
READMEを丁寧に書くことは、開発者自身の思考を整理し、利用者に安心感を与え、コミュニティを育てるための最初の一歩になります。

私がやってるような普通のWebサイトであれば、ささっと書いて済ませても十分だという話もあるんですけどね。
これから肥大化していくことが分かっているので、やっぱちゃんと書いておいた方が良いと思っているのですよ。

でも、READMEは読まれないもんですよね…

新しい電化製品を買った時、説明書を読む人と読まない人がいますよね。
それと同じで、アプリのREADMEも読まれないことが多い…
まぁそんなもん🎵

それはそれで良いと思いますし、READMEをちゃんと読むかどうかはユーザーの判断に委ねるべきでしょう。
とは言え、このサイトはそもそも個人サイト制作の初心者向けに書いたWebページも多数あるわけです。
少しでも読みやすいレイアウトで、READMEを提供したいと考えたんですよ。

githubreadme

このGitHubオリジナルREADMEもカッコいいんだけど、ちょっと技術者寄りな雰囲気で、IT初心者さんには近寄りがたいと思うんです。
私だって学生時代はそう思っていました。
それどころか、READMEなんて真面目に読んだことなかったですよ。

readmecode

でも、こうやってMarkdown記法で書いてから、改めてHTMLにするのは私としては手間がかかり過ぎます。
そういう手間が、更新への消極性となって表面化するんだよね。
いつまでも古いREADMEでは意味がありませんし、だらしない印象を与えかねません。
手間をかけず、それでいてユーザーが読みやすい新鮮なREADMEを常に提供するにはどうすれば良いか？

readmehtml1

そこで、当サイトはPythonのFlaskフレームワークを使っているので、README.mdをサーバサイドスクリプトでHTML化して、それをWebページとして表示させるというものです。
上の画像のようになります。
GitHub Pagesを使う方法もありましたが、わざわざWebサイトを分けるより、自分が今作っている既存のサイトに表示させたほうが、私自身もアクセスしやすいです。

readmehtml2

要するに README_GitHub が何をやっているかというと、次の通りです。

  1. 私がいつも通りREADME.mdを更新する
  2. README.mdはプロジェクトルートにあるから、そこにREADME.mdをHTMLに変換して返す機能を持たせたPythonスクリプトを置く
  3. README_GitHubに、私が更新したREADME.mdが反映される

そんなに複雑な仕組みじゃないです。
こうすることで、私はいつも通りREADME.mdを更新するだけで、ユーザーには読みやすいレイアウトのREADMEがリアルタイムで提供されるってことになるのですよ。
私自身も確認しやすいしね。
だって、自分が作ってるサイトに、常に最新版のREADMEが表示されているのですから。

では、さっそく作り方を見ていきましょう。

Blueprintを使って分かりやすく管理する

PythonのFlaskでアプリやるなら、Blueprintは覚えたほうが良いんじゃないかなーと思います。
Blueprintを使う意味は、Flaskアプリを「ひとつの塊」としてではなく「複数のまとまり」として捉え直すところにあります。
小さなアプリなら app.py にすべてを書き込んでも動きますが、成長していくとルーティングや機能が絡み合い、保守が難しくなります。
Blueprintはそのゴチャゴチャを整理するための仕組みで、アプリをモジュールごとに分割し、再利用可能な部品として扱えるようにします。

Blueprintを導入すると、ルートやビューを「この機能はこのまとまりに属する」と自然に整理できます。
ユーザー管理、ブログ記事、APIエンドポイントなどをそれぞれ独立したBlueprintに切り分ければ、コードの見通しが良くなり、チーム開発でも担当範囲を明確にできます。
さらに、Blueprintは「プラグイン的な拡張」を可能にします。
外部ライブラリや社内共通モジュールをBlueprintとして提供すれば、別のプロジェクトに簡単に組み込めるのです。

もうひとつの意義は「柔軟な構成管理」です。
Blueprintはアプリ本体に登録されるまで独立して存在できるため、テスト環境や本番環境で異なる構成を選びやすくなります。
例えば管理者用のルートを特定の環境だけで有効化する、といった切り替えも容易です。

つまりBlueprintは、Flaskを「小さなスクリプト」から「拡張可能なアーキテクチャ」へと進化させるための鍵というか、ポイントみたいなもんです。
コードの整理、再利用性、チーム開発の効率化、環境ごとの柔軟性――これらを同時に実現するのがBlueprintの役割です。

README.mdを表示する機能を追加する

今の私のアプリの場合、main.py はすでに Flask アプリのエントリーポイントとして動いていて、sitemap や pagelist を Blueprint で分離しています。
ここに README.md を表示する機能を追加するので、同じように Blueprint として分離するのがベストだと思いますね。

こういうページを読んでいる方には不要と思われるので、main.pyは全文書きませんし、pythonに書き込まれているhtmlも説明を省略させて頂きます。

readme.py を作成

まずはプロジェクトルートに新しいファイル readme.py を置きます。
コードは次の通りです。


import os
import markdown
from flask import Blueprint, render_template_string

bp = Blueprint("readme", __name__)

BASE_DIR = os.path.dirname(__file__)
README_PATH = os.path.join(BASE_DIR, "README.md")

@bp.route("/readme")
def readme():
    with open(README_PATH, encoding="utf-8") as f:
        content = f.read()
    html = markdown.markdown(content)
    return render_template_string("""
    <!DOCTYPE html>
    <html lang="ja">
    <head>
        <meta charset="utf-8">
        <title>README</title>
        <link rel="stylesheet" href="/static/css/style.css">
    </head>
    <body>
        {{ html|safe }}
    </body>
    </html>
    """, html=html)

このコード全体の役割は「README.mdをMarkdownからHTMLに変換し、Flaskアプリの /readme ページで表示する」ことです。
Blueprintを使っているので、アプリ本体とは独立したモジュールとして管理でき、拡張性や保守性が高まります。

import os
標準ライブラリの os モジュールを読み込みます。ファイルパスの操作やディレクトリの取得など、OS依存の処理を行うために使います。
import markdown
Markdown形式のテキストをHTMLに変換するための外部ライブラリを読み込みます。README.mdの内容をWebページで表示する際に利用します。
from flask import Blueprint, render_template_string
Flaskから Blueprint と render_template_string をインポートします。
・Blueprint はアプリをモジュール化して管理する仕組み。
・render_template_string は文字列として渡されたテンプレートを直接レンダリングする関数です。
bp = Blueprint("readme", __name__)
"readme" という名前のBlueprintを作成します。これにより、このモジュール内のルートをアプリ本体に登録できるようになります。
BASE_DIR = os.path.dirname(__file__)
現在のファイルが存在するディレクトリのパスを取得します。README.mdの場所を特定するための基準となります。
README_PATH = os.path.join(BASE_DIR, "README.md")
上で取得したディレクトリに "README.md" を結合し、READMEファイルの絶対パスを生成します。
@bp.route("/readme")
Blueprintに /readme というURLパスを登録します。このURLにアクセスすると、次の関数が呼び出されます。
def readme():
/readme にアクセスした際に実行されるビュー関数を定義します。
with open(README_PATH, encoding="utf-8") as f:
README.mdファイルをUTF-8で開きます。with 構文を使うことで、処理終了後に自動的にファイルが閉じられます。
content = f.read()
ファイルの中身をすべて読み込み、文字列として content に格納します。
html = markdown.markdown(content)
読み込んだMarkdown文字列をHTMLに変換し、html に格納します。
return render_template_string(""" ... """, html=html)
文字列として書かれたHTMLテンプレートをレンダリングし、変換済みのMarkdown（html）を埋め込みます。{{ html|safe }} によって、HTMLがエスケープされずにそのまま表示されます。
main.py に追記

既存の main.py に以下のコードを追加します。


from readme import bp as readme_bp   #
app.register_blueprint(readme_bp)    #

main.py はアプリの起動と Blueprint の登録だけに集中させ、readme.py は README.md を HTML に変換して返す機能だけを持たせるようにします。
こうすることで main.py が肥大化せず、機能ごとに整理された構成になります。
この構成であれば、https://feinatelier.org/readme にアクセスすると常に最新の README.md がレンダリングされるってことですね。

requirements.txtにMarkdownを記述する

requirements.txt は Python プロジェクトで利用するライブラリとそのバージョンを記録するためのファイルであり、開発者が同じ環境を再現できるようにする役割を持っています。
チーム開発やデプロイの際に環境の違いによる不具合を防ぎ、安定した動作を保証することができます。

Markdown==3.5.1 という記述は、Python のパッケージ管理において「Markdown」というライブラリをインストールすること、そしてそのバージョンを 3.5.1 に固定することを意味します。
これは、プロジェクトが必ずそのバージョンの Markdown ライブラリを利用するように指定する宣言であり、環境の再現性や安定した動作を保証するために用いられます。

requirements.txtは次のように記述し、プロジェクトルートに置きましょう。


Markdown==3.5.1
Flask==3.0.0
gunicorn==21.2.0

環境構築時に以下をコマンド実行します。


pip install -r requirements.txt

これで記載されたライブラリが一括でインストールされます。

なぜバージョンを固定するのかというと、ライブラリは更新されると挙動が変わることがあり、予期せぬ不具合を引き起こす可能性があるからです。
バージョンを固定しておけば「昨日は動いたのに今日は動かない」といった事故を防ぐことができます。
特に Flask アプリのようにデプロイ環境で運用する場合には、安定したバージョンを指定しておくことが基本となります。

このサイト（Flask + App Engine）の場合、デプロイ時に pip install -r requirements.txt が走るので、ここに書いてある内容がそのまま本番環境のライブラリ構成になります。

サイトマップ

全ページをリスト化したサイトマップも用意していますが、けっこうなページ数があります。
下記の「カテゴリー分けサイトマップ」のほうが使いやすいでしょう。

アナザーエデン関連ページ・サイトマップ
アナザーエデンの強敵戦やストーリーコンテンツのリスト、お勧めバッジなどを掲載したコーナーです。
期間限定のない普通のRPGですので、初心者でも安心して続けていけるゲームとなっています。
もっとも重要なグラスタについては、場所別に網羅した表があります。

個人サイトのホスティングとコンテンツ作成
個人でウェブサイトを作るなら時間をかけて。
HTML・CSS・JavaScriptの書き方はもちろん、無料かつ広告なしでホームページを作る方法を掲載したコーナーです。
Webデザインやレイアウトについても書いてあります。

魚釣りなどアウトドアのエリア
ゲームとパソコンだけじゃなく、アウトドアも趣味なんです。
このコーナーでは魚釣りの記録とか、魚料理のレシピ、はたまたサイクリングなどなど。
アウトドアに関連するコンテンツが詰め込まれています。