GitHubを使ったブログサイトの作り方

2023-07-05

Twitterが終わった今こそ、各々がWebサイトを持っていた昔のインターネットに回帰しよう。

\[ \newcommand{dn}[3]{\frac{\mathrm{d}^{#3} #1}{\mathrm{d} #2^{#3}}} \newcommand{\d}[2]{\frac{\mathrm{d} #1}{\mathrm{d} #2}} \newcommand{\dd}[2]{\frac{\mathrm{d}^2 #1}{\mathrm{d} {#2}^2}} \newcommand{\ddd}[2]{\frac{\mathrm{d}^3 #1}{\mathrm{d} {#2}^3}} \newcommand{\pdn}[3]{\frac{\partial^{#3} #1}{\partial {#2}^{#3}}} \newcommand{\pd}[2]{\frac{\partial #1}{\partial #2}} \newcommand{\pdd}[2]{\frac{\partial^2 #1}{\partial {#2}^2}} \newcommand{\pddd}[2]{\frac{\partial^3 #1}{\partial {#2}^3}} \newcommand{\p}{\partial} \newcommand{\D}[2]{\frac{\mathrm{D} #1}{\mathrm{D} #2}} \newcommand{\Re}{\mathrm{Re}} \newcommand{\Im}{\mathrm{Im}} \newcommand{\bra}[1]{\left\langle #1 \right|} \newcommand{\ket}[1]{\left|#1 \right\rangle} \newcommand{\braket}[2]{\left\langle #1 \middle|#2 \right\rangle} \newcommand{\inner}[2]{\left\langle #1 ,#2 \right\rangle} \newcommand{\l}{\left} \newcommand{\m}{\middle} \newcommand{\r}{\right} \newcommand{\f}[2]{\frac{#1}{#2}} \newcommand{\eps}{\varepsilon} \newcommand{\ra}{\rightarrow} \newcommand{\F}{\mathcal{F}} \newcommand{\L}{\mathcal{L}} \newcommand{\t}{\quad} \newcommand{\intinf}{\int_{-\infty}^{+\infty}} \newcommand{\R}{\mathcal{R}} \newcommand{\C}{\mathcal{C}} \newcommand{\Z}{\mathcal{Z}} \newcommand{\bm}[1]{\boldsymbol{#1}} \]

自由度が高く保守性も高いブログシステム（このサイト）が無料で簡単に作れちゃいます。

Pandoc

Pandocはいろんな種類の文書を変換してくれるツールです。 今回は Markdown → HTML の変換をさせます。

コマンドの使い方

Pandocはaptでインストールできます。

sudo apt update
sudo apt -y install pandoc

変換コマンドは、以下の通りです。

pandoc -f markdown -t html --template=template.html --toc --no-highlight --mathjax test.md >> test.html

-f で入力フォーマットを、-t で出力フォーマットを指定します。 このコマンドでは、入力形式にmarkdownを、出力形式にhtmlを指定しています。

--template= でテンプレートのHTMLを渡します。

--toc は目次を生成するオプションです。

--no-highlightと--mathjaxについては後述します。

最後に、変換するファイル test.md を渡してやります。

標準出力に出た変換結果をリダイレクトしてファイル test.html に保存します。

本サイトでは、以下のコマンドで変換をしています。

find . -name "*index.md" | while read i; do pandoc -f markdown -t html --template=.common/template.html --toc --no-highlight --mathjax "${i}" >> "${i%.md}.html"; done

index.md という名前のファイルを全て探索し、index.html というファイルに変換しています。

テンプレートと変数

Pandocは、markdownの中身を読み取り、HTMLに変換し、 テンプレート中の $body$ に流し込みます。

また、メタデータは、Pandoc変数を使ってテンプレートに書き込みます。

Markdown の先頭に --- で囲まれた yaml でメタデータを書くと、Pandoc変数に代入されます。

以下に例を示します。 Markdownの先頭に、

---
title: たいとる
date: 2000-00-00
description: せつめい
---

と書き、テンプレート中に、

$if(date)$
<meta name="dcterms.date" content="$date$" />
$endif$ $if(keywords)$
<meta name="keywords" content="$for(keywords)$$keywords$$sep$, $endfor$" />
$endif$ $if(description)$
<meta name="description" content="$description$" />
$endif$
<title>$if(title)$$title$$endif$ | Kanade's Website</title>

と書いておくと、$title$が、たいとる に置換されて書き込まれます。

また、上の例の$keywords$のように、if文を使って出力を制御することもできます。 この場合では、keywords変数が空なので、 $if(keywords)$~$endif$で囲まれた部分は出力されません。

詳細はドキュメント：Pandoc User’s Guide 日本語版を見てください。

本サイトのテンプレートは、https://kanade-k-1228.github.io/.common/template.htmlにあります。

GitHub

GitHub Pages

GitHub で静的サイトをホスティングできるサービスです。 単に html ファイルを置いておくだけのサイトなら作れます。 サーバーで処理が必要な機能（コメント、アクセスカウントなど）は、GitHub Pagesだけでは作れません。 （別途自分でサーバー建てればできます。）

  1. [User Name].github.io という名前のリポジトリを作る。
  2. リポジトリの Settings > Pages > Source を None から Main に変更。Main ブランチ以下が https://[UserName].github.io/ に公開されます。

GitHub Actions

GitHub Actionsでは、様々な処理をGitHubのサーバー上で行うことができます。

本サイトでは、Pandocによる Markdown → HTML 変換を、GitHub Actioinsで実行しています。

Actionsの設定は、リポジトリの .github/workflows 以下に記述します。

本サイトのActioinsのソースコードです。

name: Convert and Deploy

# main にプッシュされたときに、以下のコマンドを実行します
on:
  push:
    branches: [main]

jobs:
  convert_via_pandoc:
  # 最新のubuntu環境上で実行します
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
    # pandoc をインストールします
      - name: Install Pandoc
        run: |
          sudo apt-get update
          sudo apt-get -y install pandoc
          pandoc --version
    # RSS を生成します
      - name: Generate RSS
        run: pandoc feed.yml --template .common/template.rss >> feed.rss
    # Markdown を HTML に変換します
      - name: Convert MD to HTML
        # index.md を全て index.html に変換します
        run: find . -name "*index.md" | while read i; do pandoc -f markdown -t html --template=.common/template.html --toc --no-highlight --mathjax "${i}" >> "${i%.md}.html"; done
    # GitHub Pages 上に公開します
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./

追加の機能

RSS

RSSフィードはサイトの更新情報を記述したファイルです。

ユーザはRSSを定期的に読みに行くことで、サイトが更新されたか知ることができます。

それを自動的にやってくれるのが、RSSリーダというソフトウェアで、 好きなサイトのRSSを登録しておくと、定期的に取得しに行って、新着通知とかを出してくれます。

このシステムは、特定のサービスに依存していません。 サーバとネットワークが生きてる限り、RSSのシステムは使えます。 突然、謎のマスクマンが現れ、インターネットを完膚なきまで破壊し尽くさない限り、使えます。

ということで、RSSを書いてみましょう。

RSSのフォーマット

RSSはXML形式です。 そこまで難しくないので、ニュースサイトのRSS、たとえばYahooニュースのRSSとかを見れば、だいたいわかると思います。

各RSSタグの意味はRSS 2.0タグリファレンス、またはRSS 2.0 at Harvard Lawを見てください。

Yamlによる記述

RSSはXML形式で、人間が手書きするには複雑すぎるので、YAML 形式で書き、pandoc で変換します。

pandoc feed.yml --template template.rss >> feed.rss

参考：pandoc-rss-template

OGP

Twitterでリンクをツイートしたら、サムネイル画像が出てくる、アレです。

Twitter カード

Twitterのリンクで大きな画像を表示するには、twitter用のmetaタグを設定する必要があるみたいです。

<meta name="twitter:card" content="Twitter card type" />
<meta name="twitter:site" content="@user name” />
<meta name="twitter:domain" content="domain name" />
<meta name="twitter:title" content="title" />
<meta name="twitter:description" content="description" />
<meta name="twitter:image" content="url to image" />

cardには4種類あるようです。 - Summary Card - 正方形の小さい画像 - Summary Card with Large Image - 大きい画像 - Player Card - 動画付き - App Card - アプリへのリンク

下2つが作れるのかは未確認。

Card Validatorサ終してて草。

エンジニア向け機能

TeX数式の表示

Mathjaxを使って、TeXの数式をきれいに表示します。

マクロの設定

VSCodeの設定

コードのハイライト

highlight-js を使って、ページ内のコードに色をつけます。

  1. https://highlightjs.org/download/ から、必要な言語をポチポチして、ダウンロードする
  2. サイトのどこかにjsとcssをおいておく
  3. html中にhljsをロードするjsを書き込む
  4. Pandocのデフォルトのハイライタを使わない設定にする --no-highlight オプションを与えます。

今後追加したい機能