ドキュメント作成 on ポンコツ地方エンジニアの技術ブログ

ブログ移転の報告

Tue, 28 Apr 2026 00:00:00 +0900

移転しました

Blogger で作成していたブログを、こちらに移転しました。

最近は生成 AI が当たり前になり、自分で調べものをすることも少なくなって、記事もあまり書けていませんでしたが、これからも細々と続けていきたいと思います。

過去の記事についてはまだ全て移動できていませんが、少しずつ移動させていきます。

Jekyll で asciidoctor-diagram を使う

Tue, 27 May 2025 00:00:00 +0900

Jekyll で Asciidoc を使えるようにしたのですが、Asciidoc 内でダイアグラムを使うためには以下の設定が必要です。

Asciidoctor Diagram の有効化

Gemfile に以下を追加します。

group :jekyll_plugins do
 gem 'asciidoctor-diagram'
 gem 'asciidoctor-diagram-plantuml'
end

以下のページには記述がありませんでしたが、私の環境では asciidoctor-diagram-plantuml も必要でした。

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

生成された画像の保存

Jekyll に、ビルドプロセスの途中で Asciidoctor Diagram が出力した画像ファイルを削除しないよう指示するために、 _plugins/jekyll-ext.rb を作成し、以下を記述します。

class Jekyll::Cleaner
 def cleanup!; end
end

詳細は以下をご参照ください。

https://github.com/asciidoctor/jekyll-asciidoc?tab=readme-ov-file#preserving-generated-images

参考 URL

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

Jekyll で画像を記事と同じフォルダに置く

Fri, 21 Mar 2025 00:00:00 +0900

Jekyll では画像などは assets 配下に置くのが普通で、_post などに置いてもその中の画像は _site には出力されません。

しかし、記事内からのみ参照する画像は記事と同じフォルダにあったほうが管理しやすいです。これについては、jekyll-postfiles というプラグインを使うことで解決できました。

https://nhoizey.github.io/jekyll-postfiles/

インストール方法は、Gemfile に以下を追記するだけです。

group :jekyll_plugins do
 gem 'jekyll-postfiles'
end

参考 URL

https://nhoizey.github.io/jekyll-postfiles/

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

asciidoctor-pdf で見出し前の改ページを無効にする

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

asciidoctor-pdf で PDF を作成したときに、見出しレベル２の前に改ページが自動挿入されて無駄に余白があるページがあったので、これを無効化する方法です。

PDF 作成時に指定するテーマファイルで設定します。

https://docs.asciidoctor.org/pdf-converter/latest/theme/heading/#chapter

これを踏まえ、heading-chapter で break-before を auto に指定すれば改ページが無効になりました。

heading:
 chapter:
 break-before: auto

ただ、auto なので、場合によっては改ページされる場合もあるかもしれません。

尚、上記の設定は doctype が book の場合のみ有効なようです。

参考 URL

https://docs.asciidoctor.org/pdf-converter/latest/theme/heading/#chapter

Asciidoc で include ディレクティブを使用している場合の画像へのパス

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

画像を読み込んでいるファイルを、別の階層にあるファイルから include ディレクティブで読み込むと、相対パスの位置が変わってしまいます。

画像を読み込んでいるファイルを単体で表示したときにはそのファイルからの相対パスになりますが、include しているファイルを表示したときには、include しているファイルからの相対パスになってしまいます。

同様のことで悩んでいる方はそれなりにいるようで、実際私もかなり困っています。

とりあえずの解決方法としては、私にとっては以下の方法が一番役に立ちました。

https://stackoverflow.com/questions/75919047/images-in-various-locations-in-included-asciidoc-files

ちょっと手間ですが、include 直前で imagedir を都度セットします。

:imagesdir: hoge
include::hoge/included_file.adoc

ただし、多重で include している場合は上記では上手くいきません。
この場合は、試行錯誤の結果、以下のようにすることで上手くいきました。

ifdef::imagesdir[:imagesdir: {imagesdir}/hoge]
ifndef::imagesdir[:imagesdir: hoge]

include::hoge/included_file.adoc

imagesdir が既に定義されている（＝別のファイルから include されている）場合は、現在の imagesdir に付加する形で imagesdir を再定義します。
imagesdir が定義されていない（＝別のファイルから include されていない）場合は、前述と同じように imagesdir を定義します。

参考 URL

https://stackoverflow.com/questions/75919047/images-in-various-locations-in-included-asciidoc-files

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のアイコン画像のパスを指定

参考 URL

[VSCode] Markdown Preview Enhanced で HTML 出力する際にサイドバーの目次を入れる

Thu, 20 Jul 2023 00:00:00 +0900

ずっとやり方が分からなかったのですが、英語版のマニュアルにやり方が書いてありました。

サイドバーのTOCを生成するには、VSCode の Markdown Preview Enhanced の設定でスクリプトの実行を有効にする必要があります。

https://shd101wyy.github.io/markdown-preview-enhanced/#/html?id=configuration

尚、上記の情報は現時点の日本語版のマニュアルには書いてありませんでした。

https://shd101wyy.github.io/markdown-preview-enhanced/#/ja-jp/html?id=%e8%a8%ad%e5%ae%9a

環境

VSCode 1.80.1
Markdown Preview Enhanced v0.6.8

スクリプトの実行を有効にする

拡張機能の設定で enableScriptExecution で検索すると設定項目が表示されるのでチェックを入れます。

尚、有効にするとセキュリティリスクがありますので、その点ご注意ください。

html の出力

あとはマークダウンのプレビュー画面で右クリックし、HTML に出力するだけでサイドバーに目次が出力されます。
尚、デフォルトではサイドバーは閉じた状態となっていました。
マークダウン内に toc: true を記述すると、サイドバーが開いた状態となりました。

以下サンプルです。

---
html:
 toc: true
---

# 見出し1

## 見出し2

### 見出し3

### 見出し3

# 見出し1

## 見出し2

参考 URL

Markdown Preview Enhanced で HTML 出力に PNG 画像を base64 で埋め込む

Mon, 03 Oct 2022 00:00:00 +0900

VSCode でマークダウンを書くのに Markdown Preview Enhanced を使用していますが、HTML で出力する際、SVG は base64 で埋め込まれましたが、PNG はデフォルトでは埋め込まれません。

これについて、以下に説明があります。

https://shd101wyy.github.io/markdown-preview-enhanced/#/ja-jp/html

文書の最初に以下を記述すれば PNG が base64 で埋め込まれました。

---
html:
 embed_local_images: true
---

参考 URL

https://shd101wyy.github.io/markdown-preview-enhanced/#/ja-jp/html

MkDocs の設定いろいろ

Fri, 03 Jun 2022 00:00:00 +0900

MkDocs の細かい設定いろいろです。

必要に応じて適宜更新していきたいと思います。

URL を自動でハイパーリンクする

以下の拡張機能を有効にします。

markdown_extensions:
 - pymdownx.magiclink

Material for MkDocsで打ち消し線が動作するようにする

以下の拡張機能を有効にします。

markdown_extensions:
 - pymdownx.tilde

スペース2個でリストがインデントされるようにする

デフォルトではスペース4個でないとリストがインデントされません。
これをスペース2個でもインデントされるようにするには、mdx_truly_sane_lists という拡張機能をインストールします。

$ pip install mdx_truly_sane_lists

mkdocs.yml に以下を追記します。

markdown_extensions:
 - mdx_truly_sane_lists:
 nested_indent: 2

更新日時を表示する

$ pip install mkdocs-git-revision-date-localized-plugin

plugins:
 - search
 - git-revision-date-localized

Material for MkDocs を使っている場合はこれだけで全ページの下部に更新日時が表示されるようになります。
オプション設定で書式などを変更することもできるようです。

https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/options/

参考 URL

OpenAPI + Swagger + Redoc + GitLab Pages で API ドキュメントを管理する

Tue, 24 May 2022 00:00:00 +0900

APIドキュメントを簡単に作成・閲覧できるようにしたいと思い、OpenAPI で作成、Swagger および Redoc で表示、GitLab Pages で公開までを行いました。

概要

OpenAPI で yaml を作成
GitLab CI/CD により自動で Swagger および Redoc でビルドし、GitLab Pages に公開
ローカル環境用に Swagger および Redoc を Docker で動かす

ディレクトリ構造

今回試しに作成したファイル一式は以下となります。詳細は後述します。

$ tree -a
.
├── .gitlab-ci.yml
├── README.md
├── docker-compose.yml
├── openapi
│ └── openapi.yaml
└── public
 └── index.html

OpenAPI の yaml を作成

Open API Specification (OAS) は REST API の仕様を記述するフォーマットです。記述方法についてはググったらたくさん出てくるので割愛します。

例えば、以下のような yaml を作成します。

openapi: 3.0.0
info:
 version: 1.0.0
 title: OpenAPI Sample
paths:
 /users:
 get:
 summary: Get Users
 responses:
 '200':
 description: OK

ローカル環境の作成

ひとまず GitLab は置いておき、まずはローカル環境で Swagger および Redoc が動くようにしてみます。
３つのサービスを動かしたかったので、docker-compose 使いました。
作成した docker-compose.yml は以下です。

version: '3'
services:
 # エディター
 swagger-editor:
 image: swaggerapi/swagger-editor
 ports:
 - "8081:8080"
 # ビューワー（Swagger-UI 版）
 swagger-ui:
 image: swaggerapi/swagger-ui
 volumes:
 - ./openapi:/usr/share/nginx/html/openapi
 environment:
 API_URL: ./openapi/openapi.yaml # Swagger UIの画面を開いたときに初期値として表示するファイル
 ports:
 - '8082:8080'
 # ビューワー（Redoc 版）
 redoc:
 image: redocly/redoc
 volumes:
 - ./openapi:/usr/share/nginx/html/openapi
 environment:
 SPEC_URL: ./openapi/openapi.yaml # Redocの画面を開いたときに初期値として表示するファイル
 PORT: 8080 # nginx port(default:80)
 ports:
 - '8083:8080'

特に難しいところはないかと思います。
docker-compose up で動かしたあと、ブラウザでアクセスすればOKです。

http://localhost:8081 で Swagger Editor にアクセスして編集が行えます。
http://localhost:8082 で Swagger UI での表示を確認できます。
http://localhost:8083 で Redoc での表示を確認できます。

ただ、Swagger Editor は別にいらなかったかもしれません。
私の場合、結局 VSCode で yaml を編集し、ブラウザの表示を更新して確認、ってやってます。

閲覧に関しては Swagger より Redoc のほうが個人的に見やすいですね。

GitLab Pages で公開する

ローカルでの環境は以上で整ったので、次は GitLab に push したら自動ビルドを行って GitLab Pages に公開するように設定します。
GitLab Pages や GitLab CI/CD については割愛します。

Swagger + GitLab Pages については以下のページが参考になりました。

https://lab.astamuse.co.jp/entry/2019/11/13/114500

ただ、今回 swagger-ui-dist のバージョンを上げたので、sed コマンドで修正するファイルを index.html から swagger-initializer.js に変更する必要がありました。
これについては以下のページが参考になりました。

https://qiita.com/hidao/items/d13e7dda3da02d37dd45

Redoc + GitLab Pages については以下のページが参考になりました。

https://medium.com/hoursofoperation/auto-generate-swagger-docs-to-gitlab-pages-ca040230df3a

以上の２つを組み合わせ、最終的に作成した .gitlab-ci.yml は以下です。
Swagger と Redoc のそれぞれで閲覧できるようにディレクトリを分けてみました。
プロキシ環境下でなければプロキシ関係の設定は不要です。

image: node:18-alpine

variables:
 # プロキシサーバー
 PROXY: 'http://example:8080'
 # ドキュメントのあるディレクトリ
 DOCS_FOLDER: "swagger"
 # ドキュメントファイル
 SPEC_TO_DISPLAY: "openapi.yaml"
 # デプロイ先
 DEPLOY_SWAGGER: "public/swagger"
 DEPLOY_REDOC: "public/redoc"

cache:
 paths:
 - ./node_modules

pages:
 stage: deploy
 before_script:
 # プロキシ環境下での下準備
 - npm -g config set proxy $PROXY
 - npm -g config set https-proxy $PROXY
 - npm -g config set registry http://registry.npmjs.org/
 - npm config set strict-ssl false
 # Swagger UI
 - npm install swagger-ui-dist@4.11.1
 # Redoc
 - npm install -g redoc-cli@0.13.14
 script:
 - mkdir -p $DEPLOY_SWAGGER
 - mkdir -p $DEPLOY_REDOC
 # Swagger UI
 - cp -rp node_modules/swagger-ui-dist/* $DEPLOY_SWAGGER
 - cp -rp $DOCS_FOLDER/* $DEPLOY_SWAGGER
 - sed -i "s#https://petstore\.swagger\.io/v2/swagger\.json#$SPEC_TO_DISPLAY#g" $DEPLOY_SWAGGER/swagger-initializer.js
 # Redoc
 - redoc-cli build -o $DEPLOY_REDOC/index.html $DOCS_FOLDER/$SPEC_TO_DISPLAY
 artifacts:
 paths:
 - public
 only:
 - main

ちなみに、Swagger の yaml ファイルは GitLab 上で Swagger でプレビュー表示されるので、外部に公開する必要がなければこれで十分かもしれません。

https://blog.kyanny.me/entry/2020/08/06/012807

参考 URL

MkDocs + GitLab Pages でドキュメント管理

Mon, 23 May 2022 00:00:00 +0900

マークダウンで書いたドキュメントを簡単に管理・閲覧できるようにしたいと思い、MkDocs と GitLab Pages を使ってみました。

概要

Markdown で書いたドキュメントを MkDocs を使って静的サイトに変換します。
MkDocs のビルドは GitLab CI/CD を使って自動で行い、出力された静的サイトを GitLab Pages で公開します。
また、ローカル環境での確認用に、Docker を使って MkDocs が動作する環境を作成します。

GitLab-Runner の設定は済んでいる前提です。

ローカル環境の構築

ひとまず GitLab は置いておき、まずはローカル環境で MkDocs が動くようにしてみます。
作成した Dockerfile は以下です。

FROM python:3.9-slim

RUN pip install \
 mkdocs \
 mkdocs-material \
 pygments

CMD ["mkdocs", "serve", "-a", "0.0.0.0:8000"]

ビルドします。

$ docker build -t mkdocs .

ドキュメントの新規作成（初回のみ）

ドキュメントを何も作成していない状態でコンテナを起動するとエラーとなります。
まずはコンテナ起動時に mkdocs new doc を実行してドキュメントを新規作成しました。

docker run -it --rm \
 -u "$(id -u $USER):$(id -g $USER)" \
 -v $(pwd)/workspace:/workspace \
 --workdir="/workspace" \
 mkdocs mkdocs new doc

以下のようにファイルが作成されます。

$ tree workspace/
workspace/
└── doc
 ├── docs
 │   └── index.md
 └── mkdocs.yml

コンテナの起動

ドキュメント作成済みであれば、以下のようにしてコンテナを起動します。

docker run -it --rm \
 -u "$(id -u $USER):$(id -g $USER)" \
 -v $(pwd)/workspace:/workspace \
 -p 8000:8000 \
 --workdir="/workspace/doc" \
 mkdocs

ブラウザで http://localhost:8000 にアクセスすれば MkDocs のページが表示されます。

GitLab Pages で公開する

ローカルでの環境は以上で整ったので、次は GitLab に push したら MkDocs のビルドを行って GitLab Pages に公開するように設定します。
作成した .gitlab-ci.yml は以下です。

image: python:3.9-slim

before_script:
 - pip install --upgrade pip
 - pip install mkdocs
 - pip install mkdocs-material
 - pip install pygments

pages:
 stage: build
 script:
 - cd workspace/doc
 - mkdocs build
 - mv site ../../public
 artifacts:
 paths:
 - public
 only:
 - main

特に難しいところはないかと思います。
mkdocs build でビルドすると site に出力されるので、public にリネームして GitLab Pages に公開しています。

参考 URL

Markdown で外部の Markdown ファイルを読み込んで表示

Thu, 24 Mar 2022 00:00:00 +0900

Markdown 自体に外部ファイルを読み込んで表示する構文はないようです。

しかし、VSCode の Markdown Preview Enhanced というプラグインでは、以下のようにして外部ファイルを読み込んでプレビュー表示することができます。

@import "hoge.md"

詳しい使い方は以下に記載されています。

https://github.com/shd101wyy/markdown-preview-enhanced/blob/master/docs/ja-jp/file-imports.md

参考 URL

https://github.com/shd101wyy/markdown-preview-enhanced/blob/master/docs/ja-jp/file-imports.md

Blogger のテーマが保存できない

Thu, 24 Feb 2022 00:00:00 +0900

Blogger テーマの「HTML を編集」で保存した際、以下のように「更新できません」と表示されどうしようもなくなったことがありました。

何回試しても、「処理しています…」が長く表示された後、「更新できませんでした」と表示されます。

原因ですが、いろいろ試行錯誤してみた結果、どうやらテンプレートの文字数が多すぎたようです。

外部の JavaScript ファイルや CSS ファイルのコードを直接埋め込んでいるところがあったのですが、それを CDN から読み込むように変更したところ、正しく更新できるようになりました。

デザインを Materiapollo に変更しました

Tue, 01 Jun 2021 00:00:00 +0900

当ブログのテーマを Materiapollo というテーマに変更しました。

https://www.cottpic.com/2018/04/materiapollo-v0-9-1-release.html

このテーマについて、カスタマイズして点についてまとめておきます。

前準備

ソフトウェアエンジニアならばこういうテーマのカスタマイズも Git を使って管理しましょう。

ウィジェットのアイコンを追加

私はサイドバーに翻訳ウィジェットとかも表示しているので、それ用のアイコンを追加します。

変更前

.sidebar .widget.BlogArchive h2:before{content: "\e02f\00A0";}
.sidebar .widget.Label h2:before{content: "\e54e\00A0";}
.sidebar .widget.PopularPosts h2:before{content: "\e39f\00A0";}

変更後

BlogSearch Translate ContactForm を追加しました。

.sidebar .widget.Translate h2:before{content: "\e8e2\00A0";}
.sidebar .widget.BlogSearch h2:before{content: "\e8b6\00A0";}
.sidebar .widget.BlogArchive h2:before{content: "\e02f\00A0";}
.sidebar .widget.Label h2:before{content: "\e54e\00A0";}
.sidebar .widget.PopularPosts h2:before{content: "\e39f\00A0";}
.sidebar .widget.ContactForm h2:before{content: "\e0be\00A0";}

アイコンのコードは以下で調べられます。

https://fonts.google.com/icons

ボタンのテキストが大文字にならないようにする

Material-UI ではボタンのテキストは全て大文字になってしまうのですが、これを解除します。

READ MORE とラベルの二カ所について以下のように修正します。

変更前

<a class='btn col m12 right' expr:href='data:post.url' style='font-weight:600;'>Read more <i class='material-icons medium chevron_r'></i></a>

<a class='btn left post-per-page' expr:dir='data:blog.languageDirection' expr:href='data:label.url'><data:label.name/><b:if cond='data:showFreqNumbers'>

変更後

<a class='btn col m12 right' expr:href='data:post.url' style='font-weight:600;'>Read more <i class='material-icons medium chevron_r'></i></a>

<a class='btn left post-per-page' style='text-transform: none;' expr:dir='data:blog.languageDirection' expr:href='data:label.url'><data:label.name/><b:if cond='data:showFreqNumbers'>

テーマの色を変更

ヘッダーの色は #00acc1、ナビゲーションバーの色は #00bcd4 なので、これで検索したら修正箇所が見つかると思います。

ヘッダーの色とテキストの配置

変更前

header{height:200px;background-color: #00acc1; overflow: hidden; color: #fff; text-align: center;}
#headerleft{margin:0;}
.headerleft h1{padding-top: 85px;}

変更後

header{background-color: #212121; overflow: hidden; color: #fff;}
#headerleft{margin:0;}
.headerleft h1{padding-top: 15px;}

ナビゲーションバーの色

変更前

nav{background-color: #00bcd4;}

変更後

nav{background-color: #757575;}

ドロップダウンリストの色

変更前

nav.npin .dropdown-content li > a, .dropdown-content li > span {
 color: #00acc1;
}

変更後

nav.npin .dropdown-content li > a, .dropdown-content li > span {
 color: #212121;
}

パンくずリストの色

リンクの色と合わせました。

変更前

.breadcrumbs.card a {color: #00acc1;}

変更後

.breadcrumbs.card a {color: #2196f3;}
.breadcrumbs.card a:hover {color: #64b5f6;}

CSS の追加

見出しをはじめ、全体的にコンテンツ内のデザインが素っ気なかったり、一部デザインが崩れていたりしたので、以下の CSS を追加しました。

.marked は後述するマークダウンを適用している範囲を指定しています。

見出し

.marked h1, .marked h2, .marked h3, .marked h4, .marked h5, .marked h6 {
 margin: 1em 0;
 font-weight: bold;
 /* font-family: 'Material Icons' */
}

.marked h2 {
 padding: 0.4em;
 background: #eaf3ff;
 border-bottom: solid 3px #424242;
}

.marked h3 {
 padding-bottom: 0.4em;
 border-bottom: dotted 1px black;
}

.marked ul > li {
 list-style-type: disc;
}

.marked ul > li > ul > li {
 list-style-type: circle;
}

.marked ul > li > ul > li > ul > li {
 list-style-type: square;
}

.marked ul {
 padding: 0 0 0 40px;
}

.marked li {
 padding: 0px;
 margin: 0 0 4px 0;
}

.marked ol {
 padding: 0 2.5em;
 margin: .5em 0;
 line-height: 1.4;
 list-style-type: decimal;
}

デフォルト状態に戻したいだけなのに結構面倒です。
以下のページが参考になりました。

https://standard.shiftbrain.com/blog/reset-and-restore-list-item-marker

コードブロック

.marked pre {
 margin: 0.5em 0 1.5em 0;
 border-radius:10px;
}

.marked p > code {
 padding: 0.1em 0.3em;
 color: palevioletred;
 background: ghostwhite;
 border: 1px;
 border: solid 1px darkgray;
 border-radius: 5px;
}

テーブル

.marked table{
 border-collapse: collapse;
 width: 100%;
}

.marked table tr{
 border-top: solid 1px #d0d0d0;
 border-bottom: solid 1px #d0d0d0;
 cursor: pointer;
}

.marked table tr:hover{
 background-color: #eaf3ff;
}

.marked table th{
 padding: 15px;
 text-align: center;
 font-weight: bold;
}

.marked table td{
 padding: 15px;
}

デフォルトの画像を追加

記事中にある最初の画像がトップページに表示されますが、画像がない記事の場合は何も表示されず寂しいので、NO IMAGE と表示されるようにします。
ちなみに、画像ではなくマテリアルアイコンと文字列で作成しています。

ホーム画面の NO IMAGE

変更前

<b:if cond='data:post.firstImageUrl'><div class='md-thumb col s12 m5 l5' style='text-align: center;'><a expr:href='data:post.url'><img expr:src='data:post.firstImageUrl'/></a></div></b:if>

変更後

<div class='md-thumb col s12 m5 l5' style='text-align: center;'>
 <a expr:href='data:post.url'>
 <b:if cond='data:post.firstImageUrl'>
 <img expr:src='data:post.firstImageUrl'/>
 <b:else/>
 <div class="noimage">
 <i class="material-icons large">image</i><br/>
 <span>NO IMAGE</span>
 </div>
 </b:if>
 </a>
</div>

CSS

あとは上記に合わせて以下の CSS を追加します。

.noimage {
 color: #bdbdbd;
 font-size:30px;
 font-weight:bold;
}

.noimage-small {
 color: #bdbdbd;
 width: 42px;
 font-size:6px;
 font-weight:bold;
 text-align: center;
}

その他

その他、以下のことをやっています。

マークダウンで記事を書けるようにする

こちらの記事を参照してください。

シンタックスハイライトを設定する

こちらの記事を参照してください。

投稿日時と更新日時の表示

以下のページを参考にさせていただきました。

https://wrxsti-fan.blogspot.com/2020/06/blogger-materiapollo.html

テーマ適用後にやったこと

ウィジェットの追加（翻訳など）
フッターのウィジェットを削除
人気記事のスニペットを非表示にした
記事の作成者とコメント数を非表示にした

表示確認

以下、表示の確認です。

見出し１

見出し２

見出し３

見出し４

見出し５

リスト
- test
- test

インラインコードcodeだよ

赤文字はHTMLで

コードブロック

namespace hoge
{
 class hoge
 {
 int hoge = 0;
 }
}

テーブル

header	header	header
hoge	hoge テーブル内の改行は`<br>`で	hoge
hoge	hoge	hoge