#author("2025-07-19T09:26:25+09:00;2025-07-19T09:23:21+09:00","default:member","member") #author("2025-07-19T09:26:43+09:00;2025-07-19T09:23:21+09:00","default:member","member") *書くだけ公開！Markdown Webサイト入門 Markdownで書いてGitHubにPushするだけの、ビルド不要・無料で公開できる記事サイトの作り方 #image(main.png) -''角田 雄一'' -'''Keywords：Markdown, JavaScript, GitHub Pages, Documentation Management''' -__[[サンプルサイト>https://yuichi-853.github.io/md-site/]]__ -__[[概要集>https://drive.google.com/file/d/1Cq0d1Dj_fSqrNECYRzIJ3gmzhdm_8v_S/view?usp=sharing]]__ //[[&color(red){__プレゼン用ページ！__};>角田雄一/卒業研究/プレゼン1]] ~ **概要 ***これは何？ Markdown形式で記事を管理し、JavaScriptでHTMLに変換し、GitHub Pagesで公開するという、MarkDownを使った無料でビルド不要のWebサイト制作手法を解説するドキュメントサイト。 //&color(red){これは何か・・を簡潔に}; ~ ***背景と目的 「Markdown（マークダウン）」という記事の執筆に広く利用されている記法がある。見出しや箇条書きなどの文章構造を、シンプルな記号だけで表現できる記法であり、HTMLのような複雑なタグを使わずに、誰でも簡単に読みやすい文章を作成できるのが特徴である。 Markdown 形式で記事が管理・公開されているプラットフォームやサービスは非常に多い。特に技術系の情報発信においては、Markdown が事実上の標準となっており、__[[Zenn>https://zenn.dev/]]__や__[[Qiita>https://qiita.com/]]__などの技術ブログや、GitHubのような巨大なプラットフォームでも採用されている。また、__[[はてなブログ>https://hatena.blog/]]__といったメジャーなブログサイトもMarkdown形式に対応している。そして、我々がよく利用するソーシャルデザイン学科の学科サイトでも、実はMarkdown風の記法で記事を編集する仕組みになっている。 しかし、Markdownで書いた文章は、そのままWebサイトとして公開することはできない。__[[Jekyll>https://jekyllrb.com/]]__（ジェキル）や__[[Hugo>https://gohugo.io/]]__（ヒューゴ）といった「静的サイトジェネレーター」と呼ばれるツールを使い、HTML形式に変換（ビルド）する必要がある。しかし、これらのツールは設定や操作が難しく、初心者にとってはハードルが高い。また、環境構築やコマンド操作といった手間もかかるため、導入の障壁となっている。 そこで本プロジェクトでは、誰もが気軽にMarkdownベースの情報発信を始められるよう支援することを目的に、「Markdownを書いてGitHubにアップロードするだけで、自動的にWebサイトが更新される」という、極めてシンプルな仕組みを構築し、さらに、その使い方を丁寧に解説したドキュメントサイトを制作する。 //&color(red){プロジェクトの背景と目的}; ~ ***コンセプト -記事はMarkDown形式で記述・管理できるようにする。 -MarkDownファイルで書かれた記事をHTMLに変換する機能を、JavaScriptを使ってブラウザ上で動作するように実装する。 -Github Pagesを使い、ローカルのGit RepositoryでMarkDownファイルに変更を加えた際、GithubにPushするだけで記事を更新できるようにする。 //&color(red){基本的な考え方、枠組み、視点など}; ~ ***成果物の仕様 Webサイト //&color(red){&small(成果物の形式・サイズ・時間尺等);}; ~ //***メンバー //&color(red){共同プロジェクトの場合のみ｜メンバーと役割分担を明記}; //~ ***制作ツール ThinkPad (PC) NeoVim (テキストエディタ) //&color(red){使用するツール｜ハードウエア・ソフトウエア}; ~ ***プロジェクトの期間 プロジェクトの期間｜2025.04.11 - 2025.07.29 2025.04.11 - 2025.07.29 //&color(red){プロジェクトの期間｜20XX.XX.XX - 20XX.XX.XX }; ~ ***まとめ //&color(red){プロジェクトが完結したら「まとめ」を記載して下さい。}; MarkdownからHTMLに変換した記事は、非常に視認性が高く、整然としたデザインを実現することができた。目次を追加したことで、記事内のスムーズな移動を実現でき、コードブロックのハイライト機能も実装したことでコード部分がが非常に見やすくなり、視認性の向上を実現した。 一方、前提知識のない人々に対する、本プロジェクトの説明方法については不十分であった。背景と目的の項目に導入部分を設け、Markdown形式に関するより詳細な解説を加えることで対応したい。 ~ ~ **調査 ***現状調査 ''Markdown形式で記事が管理されているメディア'' -ITブログサイト 代表的なものとして[[Zenn>https://zenn.dev/]]と[[Qitta>https://qiita.com/]]がある。 どちらも、記事を更新するには[[Web上のエディタ>https://help.qiita.com/ja/articles/qiita-edit]]を用いる仕様であり、自分のエディタでは編集できない。 技術ブログのサイトであるため、当然サイトのカスタマイズはできない。 -一般ブログサイト 調査の結果、[[はてなブログ>https://hatena.blog/]]がMarkdown形式に対応していることがわかった。 [[はてなで使えるMarkdown記法>https://hero-rin.hatenablog.com/entry/2019/03/05/022708]]の記事にあるように、ほとんどのMarkdown記法が使え、コードブロックにまで対応している。 //&color(red){プロジェクトのテーマに関わる社会の現状と問題の洗い出し}; ~ ***先行事例 -[[Jekyll>https://jekyllrb.com/]] Rubyで書かれたMarkdownベースの静的サイトジェネレーター。 ローカル環境でのビルドが必要で、そのためにはRuby環境とJekyllのインストールが必要。 -[[Hugo>https://gohugo.io/]] Goで書かれたMarkdownベースの静的サイトジェネレーター。 Jekyll同様ビルドが必要で、GoとHugoのインストールが必要。 //&color(red){プロジェクトのテーマに該当する先行事例の紹介、傾向分析など}; ~ ***技法・技術情報 -[[Marked>https://github.com/markedjs/marked]]: MarkDownからHTMLへの変換ライブラリ -[[highlight.js>https://highlightjs.org/]]: 構文ハイライトのライブラリ //&color(red){プロジェクトの遂行に必要な技法・技術に関する調査}; ~ ~ **プロジェクト管理 -__[[スケジュール（進行管理表）>https://docs.google.com/spreadsheets/d/1E9fFEPCkIFqWmT_iNE0cEh-c3_qAvQ33HUpLjEOpElE/edit?usp=sharing]]__ //&color(red){計画的な遂行のために、進行管理表を作成してリンクして下さい。}; -__[[TODOリスト>https://github.com/yuichi-853/arch-sway-custom/blob/main/docs/TODO.md]]__ //&color(red){やるべきこと（タスク）を箇条書きにします。}; //&color(red){完了後は「%%取り消し線%%」あるいは「// コメントアウト」」}; //***NotToDo //&color(red){やらないこと：何をするかではなく「何をしないか」を考える}; //&color(red){例：10人以上の会議には出ない。苦手なことは誰かに頼む・・}; ~ ~ #hr CENTER:''進捗記録'' //&color(red){最新の情報を一番上に記載して下さい（古い記事が下へ沈む）。}; #hr ~ ~ //**2025.07.29 //***ブラッシュアップ //審査の際に「前提知識が無い人にとってわかりにくい」「説明が不十分」とのご指摘を頂いた。それを受けて、背景と目的欄に大幅な変更を加え、Markdown形式にあまり馴染みのない方でもプロジェクトについて理解できるようにした。 ~ ~ **2025.07.18 ***埋め込みYouTubeサムネイルの表示 埋め込んだYouTubeサムネイル欄の縁が丸みを帯びるようにした。 #image(marked_test_12.png) ~ ~ **2025.07.11 ***コードブロックの表示 コードブロック欄の縁が丸みを帯びるようにした。 #image(marked_test_11.png) ~ ~ **2025.07.04 ***目次の固定機能 記事をスクロールするとき、目次が画面上部に固定されて、常に表示できるようにした。 #image(marked_test_10.png) ~ ~ **2025.06.27 ***目次の固定機能 記事をスクロールするとき、目次が画面上部に固定されて、常に表示できるようにしたいのだが、Bootstrapとの兼ね合いもあり、うまくいっていない。 ~ ***概要集 フィードバックを受け、前期概要集に変更を加えた。 -__[[概要集>https://drive.google.com/file/d/1Cq0d1Dj_fSqrNECYRzIJ3gmzhdm_8v_S/view?usp=sharing]]__ ~ ~ **2025.06.20 ***コードブロックのテーマ変更 コードブロックのテーマを__[[Catppuccin>https://github.com/catppuccin/catppuccin]]__の__[[Frappé>https://catppuccin.com/palette/]]__に変更した。 #image(marked_test_9.png) ~ ***プロジェクトテーマの変更 フレームワーク制作について検討しながらも、MDからHTMLへの変換と表示についての作業は進めていたのだが、コードブロックを実装した段階で、かなり綺麗に整った記事をMDから生成できるようになっていた。 フレームワーク制作は先週、検討の結果断念したのだが、MDからこれだけきちんとしたサイトが作れるならば、Linux関連の誰も知らないテーマにするよりも、「MDを使って手軽に綺麗なサイトを作る方法を解説するWebサイトの制作」にテーマを変更したほうが、より多くの人の役に立てるのではないかと思った。 ~ ***概要集 前期概要集を制作した -__[[概要集>https://drive.google.com/file/d/1Cq0d1Dj_fSqrNECYRzIJ3gmzhdm_8v_S/view?usp=sharing]]__ ~ ~ **2025.06.13 ***目次リンク自動生成 目次リンクの見た目を整えた。また、目次のリンクをクリックすると、その見出し部分に飛ぶようにした。 #image(marked_test_8.png) ~ ***プロジェクトテーマ変更について 「MDファイルに yaml 形式でタイトル・日付・カテゴリー情報・タグ情報などを埋め込むことで、自動でサイトを生成するフレームワーク」の仕様について検討した。 結果、技術的には可能であるが、"Jekyll" という類似するフレームワークが存在していることと、ユーザーによるサイトの記事以外の箇所のカスタマイズ方法がどうしても複雑になってしまい、「MDだけで簡単にサイトを作る」という本来のコンセプトと、最低限のカスタマイズ機能との両立が非常に困難であるということから、このフレームワーク制作は断念することにした。 ~ ~ **2025.06.06 ***目次リンク自動生成 MarkDownファイルの「見出し１（#）」と「見出し２（##）」を自動で読み取って、目次が自動生成されるようにした。（画像左部） #image(marked_test_7.jpg) ~ ***プロジェクトテーマ変更について 中間報告にて、MarkDownファイルをHTMLに変換する機能のほうをテーマにしたほうが良いのではないかというアドバイスを頂いた。 変換機能をテーマとする場合、テーマとしては「MDファイルをJavaScriptを用いてHTMLに変換し、GitHub Pagesで無料公開する方法を解説したWebサイトの制作」や、「MDファイルに yaml 形式でタイトル・日付・カテゴリー情報・タグ情報などを埋め込むことで、自動でサイトを生成するフレームワークの制作」がテーマとして考えられるが、せっかくなので後者のほうをやってみようと思う。 ~ ~ **2025.05.23 ***ライブラリ動作検証 画像のパスを指定することで、画像を埋め込むことができるようにした。 MarkDown記法に則った記法で埋め込めるようにした。  #image(marked_test_6.jpg) ~ ~ **2025.05.16 ***ライブラリ動作検証 JavaScriptを使って、MarkDownファイルにYouTube動画のリンクをテキストとして貼るだけで、サイト上ではYouTube動画のサムネイルを表示し、再生できる状態で埋め込まれるようにした。 ~ #image(marked_test_5.png) ~ ~ **2025.05.09 ***コンテンツ書き出し -Arch Linuxのインストール方法の簡単な紹介とSway-wmとその他ツールのインストール方法。 -日本語 IME（入力メソッド）の設定 -Sway-wmの基本的な設定 -Waybar（ステータスバー）の設定 -Gnu Stowを用いた設定ファイルの複数デバイスでの管理法 -wofi（ランチャー・メニュー）の設定 -mako（通知デーモン）の設定 -xkbを用いたキーマップの貼り替え ~ ***ライブラリ動作検証 YouTubeリンクをMDファイルに貼り付けHTMLに変換したところ、リンクの文字列がそのまま表示された。学科サイトのように動画枠とサムネイルを表示し、そのまま再生できるようにしたい。 動画URLから自動的に動画を埋め込むプログラムを書いているが、まだうまくいっていない。 #image(marked_test_4.png) ~ ***プレゼン準備 [[__プレゼン用ページ__>角田雄一/卒業研究/プレゼン1]] ~ ~ **2025.05.02 ***ライブラリ動作検証 ''highlight.js'' の実装及び動作検証 -✅ コードブロックの構文ハイライト機能（画像はbash文） #image(marked_test_3.png) ~ ***プレゼン準備 [[__プレゼン用ページ__>角田雄一/卒業研究/プレゼン1]] ~ ~ **2025.04.25 ***ライブラリ動作検証 ''Marked'' の実装及び動作検証 -✅ MarkDown文書をHTMLに変換する機能 #image(marked_test_1.png) -✅ コードブロック表示機能 #image(marked_test_2.png) ~ ~ **2025.04.18 ***サイトの要件 Arch Linuxに関する情報は移り変わりが激しく、サイト情報の頻繁な更新が想定されるため、以下の要件を設定する。 -記事はMarkDown形式で記述・管理できること。 -Github Pagesを使い、ローカルのGit RepositoryでMarkDownファイルに変更を加えた際、GithubにPushするだけで記事を更新できること。 ~ ***実装予定機能 -ブラウザ上で動作するJavaScriptのMarkDown文書をHTMLに変換する機能 -MarkDownファイルから各章の見出し情報を取得し、目次を生成する機能 -記事をMarkDownからHTMLに変換して表示した際、コードブロックの構文ハイライト機能 -画像表示機能 -YouTube動画リンク埋め込み&表示機能 ~ ***技法・技術調査 -__[[Marked>https://github.com/markedjs/marked]]__という、MarkDown文章をHTMLに変換できるライブラリがあり、CDNか、JavaScript圧縮ファイルをサイトに組み入れることで利用できる。 -__[[highlight.js>https://highlightjs.org/]]__という、構文ハイライトのライブラリがあり、__[[この記事>https://www.nxted.co.jp/blog/blog_detail?id=1]]__によると、上記"Marked"と非常に相性が良いそうである。 ***試作 __[[サイトマップ>https://docs.google.com/presentation/d/1UMsg5QQ3sMK1BGgppFM8X8qStwkTZXpFVh0Ux7-v4BI/edit?usp=sharing]]__ ~ ~ **2025.04.11 ***テーマ決定 -Arch LinuxとSway-wmを使ったデスクトップ環境の構築方法を日本語で解説したWebサイトの制作 ~ ***現状調査 ''Sway-wmに関する日本語の情報源の調査結果'' -Googleで、「arch linux sway 設定」をキーワードとして日本語指定で検索した際、Arch LinuxでのSway-wmの設定方法に関連する''日本語の検索結果はわずか７件''。 -動画サイトYouTubeにおいては、バニラの（追加の設定やテーマ、アプリを含まない、素の状態の）Sway-wmに関する''日本語の動画はひとつも無かった''。 ~ ***先行事例調査 -IT情報共有サイト 代表的なものとして__[[Zenn>https://zenn.dev/]]__と__[[Qitta>https://qiita.com/]]__があり、どちらのサイトもMarkDown記法で、左に記事、右に目次のレイアウト。 左に目次のほうが見やすいかも。 -Sway-wmの設定ファイルの紹介・解説サイト --https://zenn.dev/haxibami/articles/wayland-sway-install 日本語の解説の中で最も詳しい。 --https://zenn.dev/eloy/articles/342e8e390e01b3 ArchLinuxのインストール方法から書かれている。Sway-wmの解説は少しだけ。 --https://zenn.dev/reviq07/articles/5736cb799b3ffc#bluetooth 設定ファイルをGithubで公開し、サイトでは実装コマンドだけ書くスタイル。各設定の詳細な解説はない。 ~ ~ ~