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