マークダウン de Webサイト！
Markdownで書いてGitHubにPushするだけの、ビルド不要・無料で公開できる記事サイトの作り方の紹介サイト
- 角田 雄一
- Keywords：Markdown, JavaScript, GitHub Pages
- サイトリンク
- 概要集
概要
これは何？
本サイトは、Markdown 形式で記事を管理し、それを JavaScript によって HTML に変換し、GitHub Pages を利用して公開するという、ビルド作業のいらない Web サイト制作手法を解説するドキュメントサイトである。
さらに、Markdown の特徴や活用方法についても解説し、Markdown を使った情報発信の利便性と仕組みを理解できるようにすることを目的としている。
背景と目的
Markdown（マークダウン）は、見出しや箇条書きといった文書構造をシンプルな記号で表現できる記法であり、HTML のような複雑なタグを使わずに、読みやすく整理された文章を記述できる。この利便性から、GitHub、Qiita、Zenn、はてなブログなど、さまざまなプラットフォームで採用されている。
一方、Markdown で作成した文章はそのまま Web ページにはならず、HTML 形式へ変換する必要がある。一般的には Jekyll や Hugo といった静的サイトジェネレーターを使用するが、環境構築やコマンド操作が必要で、複数端末での運用や長期的な管理が負担となる場合もある。
そこで本プロジェクトでは、「Markdown を書いて GitHub に Push するだけで Web サイトが更新される」仕組みを構築し、ビルド不要で継続的に管理できる Markdown ベースの Web 発信環境を提供する。
この仕組みをわかりやすくまとめたドキュメントサイトを制作し、Markdown の利便性と Web 公開の流れを整理して提示することを目的とする。
コンセプト
- 記事はすべて Markdown 形式で管理する
- Markdown ファイルを ブラウザ上の JavaScript で HTML に変換する
- GitHub Pages を用い、GitHub に Push するだけで公開が反映される仕組みを構築する
- Markdown の特徴や使い方もまとめ、Web サイト運用の基本構造を理解できるようにする
成果物の仕様
Web サイト： https://yuichi853.github.io/md-site/
Markdown 変換機能・複数レイアウトサンプル・記事テンプレートなどを含む。
制作ツール
ThinkPad（PC）
NeoVim（テキストエディタ）
プロジェクトの期間
2025.04.11 - 2025.10.24
まとめ
本プロジェクトでは、Markdown で記述した記事を JavaScript によって HTML に変換し、GitHub Pages で公開する仕組みを構築した。
これにより、従来の静的サイトジェネレーターのような環境構築やビルド作業を必要とせず、軽量で持続的な Web 発信環境を実現できた。
目次生成やコードハイライトにも対応し、視認性の高い記事デザインを実現した。一方で、Markdown の仕組みに馴染みのない人への説明は改善の余地があり、今後は導入部分の強化や全体構成の整理を通して理解しやすさを高めたい。
調査
現状調査
Markdown形式で記事が管理されているメディア
- ITブログサイト
代表的なものとしてZennとQittaがある。
どちらも、記事を更新するにはWeb上のエディタを用いる仕様であり、自分のエディタでは編集できない。
技術ブログのサイトであるため、当然サイトのカスタマイズはできない。
- 一般ブログサイト
調査の結果、はてなブログがMarkdown形式に対応していることがわかった。
はてなで使えるMarkdown記法の記事にあるように、ほとんどのMarkdown記法が使え、コードブロックにまで対応している。
先行事例
- Jekyll
Rubyで書かれたMarkdownベースの静的サイトジェネレーター。
ローカル環境でのビルドが必要で、そのためにはRuby環境とJekyllのインストールが必要。
- Hugo
Goで書かれたMarkdownベースの静的サイトジェネレーター。
Jekyll同様ビルドが必要で、GoとHugoのインストールが必要。
技法・技術情報
プロジェクト管理
進捗記録
2025.11.14
テンプレートサイト
テンプレートサイトのサンプル画像をよりシンプルなものに差し替えた。
2025.10.31
概要集修正
レイアウトの乱れや番号の打ち間違え等、細かい修正を加えた。
第三者によるサイトレビュー
Webサイトに関する知識が豊富なクラスメートの方に、サイトのコンテンツの検証とレビューをして頂いた。
サイトの使いやすさに関しては、ターミナルに触れたことのあるような、テクノロジーに詳しい人であればスムーズに使えるだろう、との感想をいただいた。
また、改善案として
- ローカルサーバー起動の実行プロンプトの書き方が紛らわしい
- サイトテンプレートのコードを編集する項目で、編集箇所の目印があるとよい
という２点をご指摘頂き、それに基づき修正を加えた。
2025.10.24
概要集
概要集を制作した。
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の設定ファイルの紹介・解説サイト
