Markdownで書いてGitHubにPushするだけの、ビルド不要・無料で公開できる記事サイトの作り方
Markdown形式で記事を管理し、JavaScriptでHTMLに変換し、GitHub Pagesで公開するという、MarkDownを使った無料でビルド不要のWebサイト制作手法を解説するドキュメントサイト。
ブログ記事や技術メモなどを効率的に管理・公開したいとき、Markdown形式（.md）を用いると、構造が明確で編集もしやすく、非常に適しています。
特にコードブロックやリスト、リンクの挿入などが簡単にできるため、 Zenn や Qiita などの技術系のブログサイトををはじめ、多くの開発者が日常的にMarkdownを活用しています。
このように、執筆や管理の面ではMarkdownが優れている一方で、MarkdownファイルをWebページとして公開するためには、Jekyll や Hugo といった静的サイトジェネレーターを使用するのが一般的です。
これらのツールは高機能ですが、ローカルにビルド環境を構築したり、コマンドによる生成処理が必要で、初心者にはややハードルが高いという課題があります。
さらに、ビルド作業を必要とするため、複数のデバイスや環境で同じように管理・運用するのが難しく、環境依存によるトラブルや手間が発生しやすくなります。
その結果、長期的なメンテナンス性にも劣るという欠点があります。
そこで本プロジェクトでは、「Markdownを書いてGitHubにPushするだけ」でサイトが自動的に更新される仕組みを構築することを目的としています。
HTMLへの変換はすべてJavaScriptでブラウザ側で行うため、サーバー側でのビルド処理や特殊な環境設定は不要です。
これにより、以下のような利点が得られます：
1ファイルごとに記事を管理できるシンプルな構成 ビルドやデプロイの手間がなく、変更の反映が高速 ローカルのエディタとGitだけで完結する効率的な作業フロー
「書く → Pushする → 公開される」というシンプルな流れで、誰でもすぐにMarkdownベースの情報発信が可能になることを目指しています。
Webサイト
ThinkPad (PC)
NeoVim (テキストエディタ)
中間報告の際、JavaScriptを使って、MarkDownでWebページを作るというコンセプトが珍しいため、それをテーマにしたプロジェクトに路線変更してはどうかと提案された。それを踏まえて、テーマ変更する際どんなアプローチができるのか探っていきたい。
Markdown形式で記事が管理されているメディア
コードブロックのテーマをCatppuccinのFrappéに変更した。
フレームワーク制作について検討しながらも、MDからHTMLへの変換と表示についての作業は進めていたのだが、コードブロックを実装した段階で、かなり綺麗に整った記事をMDから生成できるようになっていた。
フレームワーク制作は先週、検討の結果断念したのだが、MDからこれだけきちんとしたサイトが作れるならば、Linux関連の誰も知らないテーマにするよりも、「MDを使って手軽に綺麗なサイトを作る方法を解説するWebサイトの制作」にテーマを変更しようと思った。
目次リンクの見た目を整えた。また、目次のリンクをクリックすると、その見出し部分に飛ぶようにした。
「MDファイルに yaml 形式でタイトル・日付・カテゴリー情報・タグ情報などを埋め込むことで、自動でサイトを生成するフレームワーク」の仕様について検討した。
結果、技術的には可能であるが、"Jekyll" という類似するフレームワークが存在していることと、ユーザーによるサイトの記事以外の箇所のカスタマイズ方法がどうしても複雑になってしまい、「MDだけで簡単にサイトを作る」という本来のコンセプトと、最低限のカスタマイズ機能との両立が非常に困難であるということから、このフレームワーク制作は断念することにした。
MarkDownファイルの「見出し１（#）」と「見出し２（##）」を自動で読み取って、目次が自動生成されるようにした。（画像左部）
中間報告にて、MarkDownファイルをHTMLに変換する機能のほうをテーマにしたほうが良いのではないかというアドバイスを頂いた。
変換機能をテーマとする場合、テーマとしては「MDファイルをJavaScriptを用いてHTMLに変換し、GitHub Pagesで無料公開する方法を解説したWebサイトの制作」や、「MDファイルに yaml 形式でタイトル・日付・カテゴリー情報・タグ情報などを埋め込むことで、自動でサイトを生成するフレームワークの制作」がテーマとして考えられるが、せっかくなので後者のほうをやってみようと思う。
画像のパスを指定することで、画像を埋め込むことができるようにした。
MarkDown記法に則った記法で埋め込めるようにした。
JavaScriptを使って、MarkDownファイルにYouTube動画のリンクをテキストとして貼るだけで、サイト上ではYouTube動画のサムネイルを表示し、再生できる状態で埋め込まれるようにした。
YouTubeリンクをMDファイルに貼り付けHTMLに変換したところ、リンクの文字列がそのまま表示された。学科サイトのように動画枠とサムネイルを表示し、そのまま再生できるようにしたい。
動画URLから自動的に動画を埋め込むプログラムを書いているが、まだうまくいっていない。
highlight.js の実装及び動作検証
Marked の実装及び動作検証
Arch Linuxに関する情報は移り変わりが激しく、サイト情報の頻繁な更新が想定されるため、以下の要件を設定する。
Sway-wmに関する日本語の情報源の調査結果