Jekyll on heppoko blog

Jekyll で Minimal Mistakes のテーマを適用する

Thu, 19 Dec 2024 00:00:00 +0900

いろいろテーマを探してみましたが、多機能かつドキュメントが充実していたのでこれにしてみました。

以下の記事で作成した環境に対して適用します。

https://kuttsun.blogspot.com/2024/09/jekyll-docker.html

尚、デモページ、およびドキュメントは以下です。

テーマの適用

Gemfile に以下を追加します。

gem "minimal-mistakes-jekyll"

_cofig.yml でテーマを指定します。

theme: minimal-mistakes-jekyll

必要に応じて各記事のレイアウトを変更します。

layout: single

選択できるレイアウトについては以下を参照してください。

https://mmistakes.github.io/minimal-mistakes/docs/layouts/

テーマを適用するだけならこれだけで OK でした。

その他の設定

公式のドキュメントに詳しく書かれているので、ここでは個人的に必要なものだけ抜粋して記載します。

スキンを変更する

https://mmistakes.github.io/minimal-mistakes/docs/configuration/#skin

_config.yml に以下のように記述します。

minimal_mistakes_skin: "default"

記事内の目次を作成する

https://mmistakes.github.io/minimal-mistakes/docs/layouts/#table-of-contents

フロントマターで以下のように設定します。

---
toc: true
toc_label: "My Table of Contents"
toc_icon: "cog"
---

記事を広げる

https://mmistakes.github.io/minimal-mistakes/docs/layouts/#wide-page

記事を目次のスペースまで広げるには、フロントマターで以下を設定します。

classes: wide

ページの作成

_pages というフォルダを作成し、そこに記事を追加します。
_config.yml に以下を追加し、_pages フォルダのドキュメントを変換対象に指定します。

collections:
 pages:
 output: true

カテゴリごとの記事一覧ページを作成

https://mmistakes.github.io/minimal-mistakes/docs/layouts/#archive-layout

_pages に category-archive.md というファイルを作成し、以下のような内容を記述します。

---
title: "Posts by Category"
layout: categories
permalink: /categories/
author_profile: true
---

タグごとの記事一覧ページを作成

カテゴリとほぼ同じです。

https://mmistakes.github.io/minimal-mistakes/docs/layouts/#archive-layout

_pages に tag-archive.md というファイルを作成し、以下のような内容を記述します。

---
title: "Posts by Tag"
permalink: /tags/
layout: tags
author_profile: true
---

年ごとの記事一覧ページを作成

カテゴリとほぼ同じです。

https://mmistakes.github.io/minimal-mistakes/docs/layouts/#archive-layout

_pages に year-achive.md というファイルを作成し、以下のような内容を記述します。

---
title: "Posts by Year"
permalink: /year-archive/
layout: posts
author_profile: true
---

サイドバーを作成する

_data/navigation.yml を作成し、以下のような内容を記述します。

docs:
 - title: Getting Started
 children:
 - title: "Quick-Start Guide"
 url: /docs/quick-start-guide/
 - title: "Structure"
 url: /docs/structure/
 - title: "Installation"
 url: /docs/installation/
 - title: "Upgrading"
 url: /docs/upgrading/

 - title: Customization
 children:
 - title: "Configuration"
 url: /docs/configuration/
 - title: "Navigation"
 url: /docs/navigation/
 - title: "UI Text"
 url: /docs/ui-text/
 - title: "Authors"
 url: /docs/authors/
 - title: "Layouts"
 url: /docs/layouts/

 - title: Content
 children:
 - title: "Working with Posts"
 url: /docs/posts/
 - title: "Working with Pages"
 url: /docs/pages/
 - title: "Working with Collections"
 url: /docs/collections/
 - title: "Helpers"
 url: /docs/helpers/
 - title: "Utility Classes"
 url: /docs/utility-classes/

 - title: Extras
 children:
 - title: "Stylesheets"
 url: /docs/stylesheets/
 - title: "JavaScript"
 url: /docs/javascript/

サイドバーを表示させたい記事のフロントマターに以下を追加します。

sidebar:
 nav: "docs"

全ての記事に表示したい場合は、_config.yml で以下のようにデフォルト値を設定します。

defaults:
 - scope:
 path: ""
 values:
 sidebar:
 nav: "docs"
 show_date: true

画面上部にナビゲーションを作成する

https://mmistakes.github.io/minimal-mistakes/docs/navigation/

_data/navigation.yml を作成し、以下のような内容を記述します。

main:
 - title: "Quick-Start Guide"
 url: /docs/quick-start-guide/
 - title: "Posts"
 url: /year-archive/
 - title: "Categories"
 url: /categories/
 - title: "Tags"
 url: /tags/
 - title: "Pages"
 url: /page-archive/
 - title: "Collections"
 url: /collection-archive/
 - title: "External Link"
 url: https://google.com
 target: _blank

記事に投稿日を表示

https://mmistakes.github.io/minimal-mistakes/docs/configuration/#post-dates

_config.yml に以下を設定します。

defaults:
 - scope:
 path: ""
 type: posts
 values:
 show_date: true

投稿日のフォーマットを指定

https://mmistakes.github.io/minimal-mistakes/docs/configuration/#post-dates

_config.yml で以下のように設定します。

date_format: "%Y-%m-%d"

コードブロックにコピーボタンを付ける

https://mmistakes.github.io/minimal-mistakes/docs/configuration/#code-block-copy-button

_config.yml に以下を設定します。

enable_copy_code_button: true

サイト内検索を有効にする

https://mmistakes.github.io/minimal-mistakes/docs/configuration/#site-search

_config.yml に以下を追加します。

search: true

検索エンジンは変更できるようです（上記リンク参照）。

パンくずリストの作成

参考 URL

https://gwenneg.com/2024/08/17/blogging-with-minimal-effort.html

Jekyll で Asciidoc を使用する

Thu, 12 Sep 2024 00:00:00 +0900

markdown だけでなく asciidoc も使えたら便利なので。

以下の記事で作成した環境に対して asciidoc を使えるようにします。

https://kuttsun.blogspot.com/2024/09/jekyll-docker.html

調べたところ以下のプラグインを使えば出来そうだったので、これを使ってみます。

https://github.com/asciidoctor/jekyll-asciidoc

Gemfile の変更

ドキュメントの通りに、Gemfile に以下を追加します。

group :jekyll_plugins do
 gem 'jekyll-asciidoc'
end

_config.yml に以下を追加します。

plugins:
 - jekyll-asciidoc

尚、jekyll-asciidoc は他のプラグインより先に記述する必要があるそうです。
詳細は以下を参照してください。

https://github.com/asciidoctor/jekyll-asciidoc?tab=readme-ov-file#plugin-ordering

これで、_post フォルダ内に asciidoc で書いたドキュメントを追加すれば OK です。
ファイル名は Jekyll の決まりとして、YYYY-MM-DD-title.adoc のように日付が入っている必要があります。

https://jekyllrb-ja.github.io/docs/posts/

以下、サンプル通りに記事を作成してみました。

= Sample Page
:page-layout: post
:page-permalink: /sample/
:url-asciidoctor: https://asciidoctor.org

This is a sample page composed in AsciiDoc.
Jekyll converts it to HTML using {url-asciidoctor}[Asciidoctor].

[source,ruby]
puts "Hello, World!"

ただし、layuout は post に変更しています。
レイアウトについては以下。

https://qiita.com/a999/items/6c29ce072c19448ea579

これできちんと表示されることを確認しました。

include ディレクティブを使用するときの相対パス

asciidoc では include ディレクティブを使用して他の asciidoc ファイルを読み込むことができますが、このままやっても上手く描画されませんでした。
同様の内容が issue に挙がっていました。

https://github.com/asciidoctor/jekyll-asciidoc/issues/182

ベースディレクトリの設定がデフォルトではプロジェクトルートになっているので、ソースディレクトリとなるように設定すれば良さそうです。

https://github.com/asciidoctor/jekyll-asciidoc?tab=readme-ov-file#specifying-the-base-directory

_config.yml に以下を追記すれば上手くいきました。

asciidoctor:
 base_dir: :docdir
 safe: unsafe

参考 URL

Jekyll + Docker で静的サイトを作成する

Wed, 11 Sep 2024 00:00:00 +0900

一番基本的なところを試してみたかっただけなのですが、嵌ったのでメモしておきます。

公式の Docker イメージは以下のようなのでこれを使いますが、長い間メンテナンスされていないようです。

https://hub.docker.com/r/jekyll/jekyll/

環境

Ubuntu 20.04
docker 24.0.7

新規作成

まずはドキュメントに従って、以下のコマンドでブログを新規作成してみます。

export site_name="my-blog"
docker run --rm \
 --volume="$PWD:/srv/jekyll" \
 -it jekyll/jekyll \
 sh -c "chown -R jekyll /usr/gem/ && jekyll new $site_name" \
 && cd $site_name

以下のエラーが出て失敗します。

/usr/local/lib/ruby/3.1.0/fileutils.rb:243:in `mkdir': Permission denied @ dir_s_mkdir - /srv/jekyll/my-blog (Errno::EACCES)

これでかなり嵌ったのですが、以下の記事を見つけました。

https://stackoverflow.com/questions/57503011/unable-to-build-cloned-jekyll-site-jekyll-3-8-5-error-permission-denied-d

どうやら環境変数を指定すればいいそうです。

export site_name="my-blog"
docker run --rm \
 -e JEKYLL_UID=1001 \
 -e JEKYLL_GID=1001 \
 --volume="$PWD:/srv/jekyll" \
 -it jekyll/jekyll \
 sh -c "chown -R jekyll /usr/gem/ && jekyll new $site_name" \
 && cd $site_name

これで、my-blog というフォルダが作成され、中に Jekyll のブログの雛形が作成されています。

ビルド

上記で作成した内容をビルドして静的サイトを生成します。
引き続き、環境変数を指定したうえでドキュメント通りに以下を実行します。

export site_name="my-blog"
docker run --rm \
 -e JEKYLL_UID=1001 \
 -e JEKYLL_GID=1001 \
 --volume="$PWD/$site_name:/srv/jekyll" \
 -it jekyll/jekyll \
 jekyll build

my-blog の中に _site というフォルダが出力されました。

サーバー起動

次はサーバーを起動してブラウザからアクセスしてみます。
こちらも引き続き、環境変数を指定したうえでドキュメント通りに以下を実行します。

export site_name="my-blog"
docker run --rm \
 -e JEKYLL_UID=1001 \
 -e JEKYLL_GID=1001 \
 --volume="$PWD/$site_name:/srv/jekyll" \
 -p 4000:4000 \
 -it jekyll/jekyll \
 jekyll serve --force_polling --livereload --host 0.0.0.0

以下のエラーが出ました。

<internal:/usr/local/lib/ruby/site_ruby/3.1.0/rubygems/core_ext/kernel_require.rb>:85:in `require': cannot load such file -- webrick (LoadError)

webrick がないそうなので、my-blog 内の Gemfile に以下を追加します。

gem "webrick"

これで上記のコマンドを実行すれば無事サーバーが起動し、http://localhost:4000 にアクセスすることで閲覧できました。

所感

公式の Docker イメージ使って基本的なことを確認したかっただけなのに全然動かねぇじゃんって思いました。

参考 URL

https://stackoverflow.com/questions/57503011/unable-to-build-cloned-jekyll-site-jekyll-3-8-5-error-permission-denied-d

asciidoctor-pdf で admonition のアイコンを別の画像に差し替える

Mon, 09 Sep 2024 00:00:00 +0900

アイコン画像を別で用意して、それに差し替える方法です。

ドキュメント内で以下のように記述して、アイコンを画像ベースの設定に変更します。

:icons: image

そのうえで、PDF 作成用のテーマファイルで以下のように画像を指定します。

admonition:
 icon:
 note:
 image: '' # NOTEのアイコン画像のパスを指定
 caution:
 image: '' # CAUTIONのアイコン画像のパスを指定