JekyllでGitHub Pagesにブログを開設した

環境
無料ユーザの場合は公開リポジトリでないといけない
*.html拡張子のファイルをliquidテンプレートとして扱う
MathJaxの設定
Reference

Jekyll+GitHub Pagesのサイト構築でハマったことを書く。基本的にはGitHubの公開している公式の手順[1]をもとに進めた。

環境

Mac OSX
VSCode

無料ユーザの場合は公開リポジトリでないといけない

[1]によると、無料ユーザの場合はPagesに公開するページのソースは公開リポジトリである必要がある。 Proユーザや企業ユーザの場合は非公開リポジトリでもOKらしい。

*.html拡張子のファイルをliquidテンプレートとして扱う

Jekyllでは*.htmlのファイルにliquidというテンプレート言語を使うことができる。デフォルトだとHTML用に自動フォーマットするとファイルの内容が壊れる。 .vscode/settings.jsonに以下の設定を追加して*.html拡張子のファイルを*.liquid拡張子として扱うようにする。

    "[jekyll]": {
        "editor.quickSuggestions": {
            "comments": "on",
            "strings": "on",
            "other": "on"
        },
        "editor.formatOnSave": true,
        "editor.wordWrap": "on",
        "editor.renderWhitespace": "all",
        "editor.acceptSuggestionOnEnter": "off"
    },
    "files.associations": {
        "*.html": "liquid",
        "*.liquid": "liquid",
    },

MathJaxの設定

外部JSを動的に読み込むことで実現する。[4]によればGitHub Pagesで扱う場合はMathJaxしか利用できないという記述がある。特にMathJax以外を使う理由もないのでMathJaxを使うことにする。外部CSSを挿入するには、テンプレートの<head>...</head>部分を修正する必要がある。 minimaテンプレートの資材を全部ローカルにコピーして編集することにした。なお、bundleでインストールしたテンプレートのローカルのインストールパスは以下で確認することができる。

bundle info --path minima

外部JSの読み込み設定

_includes/head-mathjax.htmlというファイルを作成し、_includes/head.htmlからこのファイルをincludeする設定を記述する。ファイルの記述内容は[2]を参考にした。前半のinlineMathの設定は $...$ でインライン数式を使えるようにするもの。

<script>
MathJax = {
  tex: {
    inlineMath: [['$', '$'], ['\\(', '\\)']]
  },
  svg: {
    fontCache: 'global'
  }
};
</script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

レンダリングエンジンの設定

[3]によれば、GitHub Flavoured Markdown(GFM)とkramdown[5]の両方に対応しているという記述がある。 kramdownだとURLを自動的にリンクとして扱わないようなのでデフォルトのGFMを選択した。

_config.yamlに以下の設定をする。

markdown: GFM # `kramdown` or `GFM`

投稿の雛形作成の自動化

Jekyllでブログを書く上での面倒なのは、postを自動生成するAPIが提供されていないことで、毎回ファイル名やdateのコンフィグを手動で入力する必要がある。

以下のようなrakeタスクを実装しておけば rake post TITLE="Hello, World"と実行すれば_posts配下に本日の日付でYYYY-MM-DD-hello-world.mdというファイルを自動で生成してくれる。コードは[7]に掲載されていたものを参考にした。

Rakefileという名前のファイルを作成して以下のコードを記述する。

require 'time'

desc 'create a new draft post'
task :post do
    title = ENV['TITLE']
    if title.nil? || title.strip.empty?
        puts "ERROR: Please provide a TITLE. Example: rake post TITLE='My Post Title'"
        exit(1)
    end

    slug = "#{Date.today}-#{title.downcase.gsub(/[^\w]+/, '-')}"

    file = File.join(
        File.dirname(__FILE__),
        '_posts',
        slug + '.md'
    )

    timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S %z')

    File.open(file, "w") do |f|
        f << <<-EOS
---
layout: post
title: #{title}
date: #{timestamp}
categories: tech
latex: true
---
EOS
    end
    puts "New post created successfully: #{file}"
end

😗 JekyllでGitHub Pagesにブログを開設した

Dec 28, 2024

Table of Contents

環境