マークダウン de Webサイト！
Markdownで書いてGitHubにPushするだけの、ビルド不要・無料で公開できる記事サイトの作り方
- 角田 雄一
- Keywords：Markdown, JavaScript, GitHub Pages, Documentation Management
- サイトリンク
- 概要集
概要
これは何？
本サイトは、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を知らなかった人々にとっても利用可能な知識基盤を提供する。
コンセプト
- 記事はMarkdown形式で記述・管理できるようにする。
- Markdownファイルで書かれた記事をHTMLに変換する機能を、JavaScriptを使ってブラウザ上で動作するように実装する。
- GitHub Pagesを用い、ローカルのGit RepositoryでMarkdownファイルを更新し、GitHubにPushするだけでWebサイトに反映できるようにする。
- Markdownそのものの基礎や利便性について解説し、初心者や未経験者でも理解できる内容とする。
成果物の仕様
Webサイト
制作ツール
ThinkPad (PC)
NeoVim (テキストエディタ)
プロジェクトの期間
2025.04.11 - 2025.07.29
まとめ
MarkdownからHTMLに変換した記事は、非常に視認性が高く、整然としたデザインを実現することができた。目次を追加したことで、記事内のスムーズな移動を実現でき、コードブロックのハイライト機能も実装したことでコード部分がが非常に見やすくなり、視認性の向上を実現した。
一方、前提知識のない人々に対する、本プロジェクトの説明方法については不十分であった。背景と目的の項目に導入部分を設け、Markdown形式に関するより詳細な解説を加えることで対応したい。
調査
現状調査
Markdown形式で記事が管理されているメディア
- ITブログサイト
代表的なものとしてZennとQittaがある。
どちらも、記事を更新するにはWeb上のエディタを用いる仕様であり、自分のエディタでは編集できない。
技術ブログのサイトであるため、当然サイトのカスタマイズはできない。
- 一般ブログサイト
調査の結果、はてなブログがMarkdown形式に対応していることがわかった。
はてなで使えるMarkdown記法の記事にあるように、ほとんどのMarkdown記法が使え、コードブロックにまで対応している。
先行事例
- Jekyll
Rubyで書かれたMarkdownベースの静的サイトジェネレーター。
ローカル環境でのビルドが必要で、そのためにはRuby環境とJekyllのインストールが必要。
- Hugo
Goで書かれたMarkdownベースの静的サイトジェネレーター。
Jekyll同様ビルドが必要で、GoとHugoのインストールが必要。
技法・技術情報
プロジェクト管理
進捗記録
2025.10.17
記事の加筆・修正
- 「マークダウンとは」と「マークダウンでWebサイト制作」の記事を大幅に加筆・修正した。
- 「マークダウンとは」の記事では、冗長な説明や、わかりにくい説明を修正した。
- 「マークダウンでWebサイト制作」の記事では、テンプレートサイトの導入方法をMac・Windowsの両システムに対応したより詳しい説明を、ステップバイステップ形式で細かく解説するようにした。そして、テンプレートサイトのカスタマイズ方法の詳細な解説も加えた。
デバッグ
- 画面幅に応じた「目次」「記事」「余白」の幅を調整し、完全にレスポンシブ対応させた。
- スマホ画面で、「目次」が「記事」の上に覆い被さって表示されていたため、修正した。
- 見出しのレベルと名前が同一の見出しの項目がある場合、それぞれをを区別できず、片方の見出しリンクが機能していなかったため、それぞれを区別できるようにした。
2025.10.10
記事ページデザイン刷新
- 記事ページのデザインをメインページの雰囲気に合うよう刷新した。
- 背景色だけでなく、目次や、Markdown記事の表示デザインもサイトの雰囲気に合うよう明るいモダンな印象に調整した。
テンプレートページ作成
- ユーザーにテンプレートを配布するページを制作した。
- 「テンプレートサイトのプレビューリンク」「Githubリポジトリへのリンク」「ダウンロードリンク」の３つのボタンを配置した。
- 右側でプレビューをざっと確認できるようにした。
Aboutページ作成
- Aboutページを制作した。
- 自己紹介と、サイトについての簡単な説明を掲載した。
2025.10.03
メインページ
- メインページを作成した。
- メインページはBootstrapやTailwindCSSのように、サイトの特徴を簡潔に伝えられるように意識した。
- デザインはBootstrapのメインページを参考にし、背景に明るいグラデーションをつけ、軽やかでモダンな印象を意識した。
- 「シンプルさ」をコンセプトの中心に据えたMarkdownを扱っているため、装飾を最小限に抑え、余白を多く取り、読みやすさを重視した。
- 右側のウィンドウ風のオブジェクトは、サイトの特徴を一目で理解できる概要パネルとして配置した。
ヘッダー
- メインページの雰囲気に合わせて、ヘッダーのデザインも変更を加えた。
2025.09.26
記事執筆
- 「マークダウンとは」という記事を書き終えた。
- 「マークダウンでWebサイト制作」という記事を書き終えた。
目次の見た目修正
「見出し１」が太字で表示されるようにし、視認性を向上させた。
2025.09.19
レスポンシブ対応
サイトをレスポンシブ対応させた。
サイトマップ
サイトマップを作成した。
ワイヤーフレーム
テンプレート
ユーザーが簡単に使用できるようにテンプレートを作成することにした。
現在テンプレートの制作途中である。
2025.07.29
ブラッシュアップ
審査の際に「前提知識が無い人にとってわかりにくい」「説明が不十分」とのご指摘を頂いた。それを受けて、背景と目的欄に大幅な変更を加え、Markdown形式にあまり馴染みのない方でもプロジェクトについて理解できるようにした。
2025.07.18
埋め込みYouTubeサムネイルの表示
埋め込んだYouTubeサムネイル欄の縁が丸みを帯びるようにした。
2025.07.11
コードブロックの表示
コードブロック欄の縁が丸みを帯びるようにした。
2025.07.04
目次の固定機能
記事をスクロールするとき、目次が画面上部に固定されて、常に表示できるようにした。
2025.06.27
目次の固定機能
記事をスクロールするとき、目次が画面上部に固定されて、常に表示できるようにしたいのだが、Bootstrapとの兼ね合いもあり、うまくいっていない。
概要集
フィードバックを受け、前期概要集に変更を加えた。
2025.06.20
コードブロックのテーマ変更
コードブロックのテーマをCatppuccinのFrappéに変更した。
プロジェクトテーマの変更
フレームワーク制作について検討しながらも、MDからHTMLへの変換と表示についての作業は進めていたのだが、コードブロックを実装した段階で、かなり綺麗に整った記事をMDから生成できるようになっていた。
フレームワーク制作は先週、検討の結果断念したのだが、MDからこれだけきちんとしたサイトが作れるならば、Linux関連の誰も知らないテーマにするよりも、「MDを使って手軽に綺麗なサイトを作る方法を解説するWebサイトの制作」にテーマを変更したほうが、より多くの人の役に立てるのではないかと思った。
概要集
前期概要集を制作した
2025.06.13
目次リンク自動生成
目次リンクの見た目を整えた。また、目次のリンクをクリックすると、その見出し部分に飛ぶようにした。
プロジェクトテーマ変更について
「MDファイルに yaml 形式でタイトル・日付・カテゴリー情報・タグ情報などを埋め込むことで、自動でサイトを生成するフレームワーク」の仕様について検討した。
結果、技術的には可能であるが、"Jekyll" という類似するフレームワークが存在していることと、ユーザーによるサイトの記事以外の箇所のカスタマイズ方法がどうしても複雑になってしまい、「MDだけで簡単にサイトを作る」という本来のコンセプトと、最低限のカスタマイズ機能との両立が非常に困難であるということから、このフレームワーク制作は断念することにした。
2025.06.06
目次リンク自動生成
MarkDownファイルの「見出し１（#）」と「見出し２（##）」を自動で読み取って、目次が自動生成されるようにした。（画像左部）
プロジェクトテーマ変更について
中間報告にて、MarkDownファイルをHTMLに変換する機能のほうをテーマにしたほうが良いのではないかというアドバイスを頂いた。
変換機能をテーマとする場合、テーマとしては「MDファイルをJavaScriptを用いてHTMLに変換し、GitHub Pagesで無料公開する方法を解説したWebサイトの制作」や、「MDファイルに yaml 形式でタイトル・日付・カテゴリー情報・タグ情報などを埋め込むことで、自動でサイトを生成するフレームワークの制作」がテーマとして考えられるが、せっかくなので後者のほうをやってみようと思う。
2025.05.23
ライブラリ動作検証
画像のパスを指定することで、画像を埋め込むことができるようにした。
MarkDown記法に則った記法で埋め込めるようにした。
2025.05.16
ライブラリ動作検証
JavaScriptを使って、MarkDownファイルにYouTube動画のリンクをテキストとして貼るだけで、サイト上ではYouTube動画のサムネイルを表示し、再生できる状態で埋め込まれるようにした。
2025.05.09
コンテンツ書き出し
- Arch Linuxのインストール方法の簡単な紹介とSway-wmとその他ツールのインストール方法。
- 日本語 IME（入力メソッド）の設定
- Sway-wmの基本的な設定
- Waybar（ステータスバー）の設定
- Gnu Stowを用いた設定ファイルの複数デバイスでの管理法
- wofi（ランチャー・メニュー）の設定
- mako（通知デーモン）の設定
- xkbを用いたキーマップの貼り替え
ライブラリ動作検証
YouTubeリンクをMDファイルに貼り付けHTMLに変換したところ、リンクの文字列がそのまま表示された。学科サイトのように動画枠とサムネイルを表示し、そのまま再生できるようにしたい。
動画URLから自動的に動画を埋め込むプログラムを書いているが、まだうまくいっていない。
プレゼン準備
プレゼン用ページ
2025.05.02
ライブラリ動作検証
highlight.js の実装及び動作検証
- ✅ コードブロックの構文ハイライト機能（画像はbash文）
プレゼン準備
プレゼン用ページ
2025.04.25
ライブラリ動作検証
Marked の実装及び動作検証
- ✅ MarkDown文書をHTMLに変換する機能
- ✅ コードブロック表示機能
2025.04.18
サイトの要件
Arch Linuxに関する情報は移り変わりが激しく、サイト情報の頻繁な更新が想定されるため、以下の要件を設定する。
- 記事はMarkDown形式で記述・管理できること。
- Github Pagesを使い、ローカルのGit RepositoryでMarkDownファイルに変更を加えた際、GithubにPushするだけで記事を更新できること。
実装予定機能
- ブラウザ上で動作するJavaScriptのMarkDown文書をHTMLに変換する機能
- MarkDownファイルから各章の見出し情報を取得し、目次を生成する機能
- 記事をMarkDownからHTMLに変換して表示した際、コードブロックの構文ハイライト機能
- 画像表示機能
- YouTube動画リンク埋め込み&表示機能
技法・技術調査
- Markedという、MarkDown文章をHTMLに変換できるライブラリがあり、CDNか、JavaScript圧縮ファイルをサイトに組み入れることで利用できる。
- highlight.jsという、構文ハイライトのライブラリがあり、この記事によると、上記"Marked"と非常に相性が良いそうである。
試作
サイトマップ
2025.04.11
テーマ決定
- Arch LinuxとSway-wmを使ったデスクトップ環境の構築方法を日本語で解説したWebサイトの制作
現状調査
Sway-wmに関する日本語の情報源の調査結果
- Googleで、「arch linux sway 設定」をキーワードとして日本語指定で検索した際、Arch LinuxでのSway-wmの設定方法に関連する日本語の検索結果はわずか７件。
- 動画サイトYouTubeにおいては、バニラの（追加の設定やテーマ、アプリを含まない、素の状態の）Sway-wmに関する日本語の動画はひとつも無かった。
先行事例調査
- IT情報共有サイト
代表的なものとしてZennとQittaがあり、どちらのサイトもMarkDown記法で、左に記事、右に目次のレイアウト。
左に目次のほうが見やすいかも。
- Sway-wmの設定ファイルの紹介・解説サイト
