Markdownで書いてGitHubにPushするだけの、ビルド不要・無料で公開できる記事サイトの作り方
本サイトは、Markdown形式で記事を管理し、JavaScriptでHTMLに変換し、GitHub Pagesで公開するという、無料でビルド不要のWebサイト制作手法を解説するドキュメントサイトである。
さらに、Markdownそのものの基礎や利便性についても紹介し、初心者やこれまでMarkdownに馴染みのなかった人に向けて、その魅力と活用方法を伝えることを目的としている。
「Markdown（マークダウン）」は、記事の執筆や情報発信に広く利用されている記法である。見出しや箇条書きといった文章構造を、シンプルな記号だけで表現できるのが特徴であり、HTMLのような複雑なタグを使わずに誰でも直感的に読みやすい文章を作成できる。そのため、技術ブログやプラットフォームにおいて事実上の標準となっている。
たとえば、ZennやQiitaといった技術系サイト、はてなブログのような大手ブログサービス、さらにはGitHubといった開発者向けプラットフォームでもMarkdownは採用されている。また、我々が利用するソーシャルデザイン学科の学科サイトもMarkdown風の記法で記事編集が行える仕組みになっている。
一方で、Markdownで書いた文章をそのままWebサイトとして公開することはできない。Jekyll（ジェキル）やHugo（ヒューゴ）などの「静的サイトジェネレーター」を使ってHTMLに変換（ビルド）する必要があるが、これらは環境構築やコマンド操作が必要で、初心者にとっては導入の大きな壁となっている。
そこで本プロジェクトでは、誰もが手軽にMarkdownを用いた情報発信を始められる仕組みを構築する。具体的には、「Markdownで文章を書いてGitHubにアップロードするだけで、自動的にWebサイトが更新される」という、極めてシンプルなワークフローを実現する。そして、その使い方をわかりやすく解説したドキュメントサイトを制作することで、技術者のみならず初心者やMarkdownを知らなかった人々にとっても利用可能な知識基盤を提供する。
Webサイト
ThinkPad (PC)
NeoVim (テキストエディタ)
2025.04.11 - 2025.07.29
MarkdownからHTMLに変換した記事は、非常に視認性が高く、整然としたデザインを実現することができた。目次を追加したことで、記事内のスムーズな移動を実現でき、コードブロックのハイライト機能も実装したことでコード部分がが非常に見やすくなり、視認性の向上を実現した。
一方、前提知識のない人々に対する、本プロジェクトの説明方法については不十分であった。背景と目的の項目に導入部分を設け、Markdown形式に関するより詳細な解説を加えることで対応したい。
Markdown形式で記事が管理されているメディア
「見出し１」が太字で表示されるようにし、視認性を向上させた。
サイトをレスポンシブ対応させた。
サイトマップを作成した。
ユーザーが簡単に使用できるようにテンプレートを作成することにした。
現在テンプレートの制作途中である。
審査の際に「前提知識が無い人にとってわかりにくい」「説明が不十分」とのご指摘を頂いた。それを受けて、背景と目的欄に大幅な変更を加え、Markdown形式にあまり馴染みのない方でもプロジェクトについて理解できるようにした。
埋め込んだYouTubeサムネイル欄の縁が丸みを帯びるようにした。
コードブロック欄の縁が丸みを帯びるようにした。
記事をスクロールするとき、目次が画面上部に固定されて、常に表示できるようにした。
記事をスクロールするとき、目次が画面上部に固定されて、常に表示できるようにしたいのだが、Bootstrapとの兼ね合いもあり、うまくいっていない。
フィードバックを受け、前期概要集に変更を加えた。
コードブロックのテーマを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に関する日本語の情報源の調査結果