この記事は DevRel Advent Calendar 2022 の 6 日目の記事です。
授業資料やハンズオン資料に使っている HonKit の設定メモについて書きます。今後も変化していくと思うので 2022 年 12 月版のものです。
ハンズオン資料づくりで自分が求めていること
私が技術を伝える授業資料やハンズオンイベントなどで資料を作っていると、必要なこととして、以下にようなことがあります。
- 環境を整えるインストールや最低限使えるまでの設定がある程度やりやすいこと
- Markdown で書いてガシガシ資料が作れること
- GitHub Pages など静的なページ公開だけで資料ページの設定ができる
- ある程度デフォルトの設定でも良い感じの資料の見た目になること
- ソースコードに関してはちゃんとシンタックスハイライトがされて参加者がソースが読みやすいこと
- 参加者がソースコードをミスなく全文コピーができる
- 資料全体にわたるインデックスが常に表示されて参加者に案内しやすいこと
- あとあと思い出したり他資料で流用するときにも脳に優しく思い出せるシンプル寄りな設定
以前、GitBook のホスティングサービスで授業資料をつくって、今回挙げたような項目がかなり作りやすく、ガシガシ Markdown で作っていけて制作体験がとてもよかったのがベースになっています。
ただ Gitbook はホスティングサービスなのでロックインされてサービスから離れづらく、他のところへの設置がやりづらいところがあるので、もう少しライトに同じような制作体験にならないかと考えていました。
Honkit をよくつかってます
そんなわけで、私は Honkit で手元で Markdown でつくりつつ HTML に書き出し、コミットして GitHub Pages で公開してハンズオン資料を作っています。
honkit/honkit: HonKit is building beautiful books using Markdown – Fork of GitBook
HonKit は「HonKit is building beautiful books using Markdown – Fork of GitBook」とあるように、もともと Gitbook がまだホスティングサービスになる前、手元で Node.js で回していた時期のソースコードをフォークして育ってきたものです、2022 年 12 月現在でも更新されていて、書き出しの高速化などチューニングされています。
最近でも、このようなシーンで使っています。
Hack Rock Fes 2022 というクローズドハッカソンで M5Stack と enebular のテクニカルメンターをしてきました
GitHub にテンプレートを作っています
使い勝手が整ってきて、毎度設定を思い出すのが大変になってきたので、GitHub のテンプレートを作ってコピーして使っています。先ほどお伝えした、授業やハンズオンでもベースに使っています。
あくまで自分用ですので、自分の使い勝手重視で作っているため、更新はあまりしないですがご参考までに。
README には、テンプレートとしてリポジトリをコピーしたら手元にクローンして設定する手順が書いています。
- GitHub 側で GitHub Pages を doc フォルダをターゲットに公開する
- 手元で Honkit のビルドをしてサンプル Markdown をベースに HTML 書き出し
- コミットして GitHub Pages でページが見れる
という流れですぐにはじめることができます。
こんな感じです。
大まかなつくりの紹介
私のテンプレートを参考いただくとしても、使われるときにはカスタマイズされると思いますが、大まかなつくりを簡単に紹介しておきます。
honkit-base/package.json at main · 1ft-seabass/honkit-base
まず、package.json の構成。Honkit は Node.js ベースでファイルの生成ができます。こちらに設定がまとめられるのは「環境を整えるインストールや最低限使えるまでの設定がある程度やりやすいこと」「あとあと思い出したり他資料で流用するときにも脳に優しく思い出せるシンプル寄りな設定」のあたりを満たします。
プラグイン
Honkit は Gitbook のプラグインも引き続き使えるので、このあたりを使っています。
"dependencies": {
"gitbook-plugin-advanced-emoji": "^0.2.2",
"gitbook-plugin-anchors": "^0.7.1",
"gitbook-plugin-back-to-top-button": "^0.1.4",
"gitbook-plugin-copy-code-button": "0.0.2",
"gitbook-plugin-hide-published-with": "0.0.1",
"gitbook-plugin-intopic-toc": "^1.1.1"
}
- gitbook-plugin-advanced-emoji
- 絵文字を表示する。絵文字で装飾しないので最近使ってないかも。
- gitbook-plugin-anchors
- アンカーの自動生成
- gitbook-plugin-back-to-top-button
- トップへ戻るボタンを設置。授業で便利。
- gitbook-plugin-copy-code-button
- 「参加者がソースコードをミスなく全文コピーができる」が実現できるコピーボタン設置
- gitbook-plugin-hide-published-with
- デフォルトで表示されている Published with Gitbook を消す
- gitbook-plugin-intopic-toc
- ページ内の目次を作る（資料全体の目次ではなくページ内）
プラグインでいろいろ拡張できるので、じっくり育てていきたいところですが、あまり増やしすぎると書き出しで重くなったりしますし、なるべくデフォルトでもうまく扱うというところから離れてしまうので、シンプルを維持できるよう注意しながら使っています。
honkit-base/book.json at main · 1ft-seabass/honkit-base
Honkit の設定ファイルである book.json 側でプラグイン実際に使う設定をしています。advanced-emoji 以外使ってますね。
{
"title":"タイトル",
"description":"詳細説明",
"language":"ja",
"plugins":[
"anchors",
"hide-published-with",
"copy-code-button",
"intopic-toc",
"back-to-top-button"
]
}
title や description は、最初は決めづらくても早めに決めるのが大事。といいつつ、開催直前に整えがちなのは私の課題です！
scripts
"scripts": {
"serve": "honkit serve base src",
"build": "honkit build base docs"
}
scriptsによる書き出し設定はこうしています。scripts 内ではプロジェクト内にインストール済みのコマンドが叩けるので honkit コマンドで始まって大丈夫です。（実はそういうルールを忘れてて、最初のころはよくハマった）
手元でテストサーバーで見た目を確認するときは npm run server コマンドで src フォルダに書き出してます。コミットして公開するためのビルド時は npm run build コマンドで GitHub Pages の公開ターゲットフォルダである docs フォルダに書き出しています。
src フォルダと docs フォルダ、テストサーバー時と公開時に書き出されるソースほぼほぼ同じそうなので別に分けなくてもよさそうなんですが、src フォルダで半端にテストしてたソースをうっかり公開するのを避けたいので、明示的に分けてる感じです。たいへんに泥臭い現場の安全策ってやつです。
.gitignore ファイル
honkit-base/.gitignore at main · 1ft-seabass/honkit-base
.gitignore ファイルに関しては、通常の Node.js の設定まわりと src フォルダの無視をしています。これは serve コマンドで手元でテストサーバーを起動するときに書き出される一時ファイル的なもので、公開時に何も関係しないので除外しています。
レイアウトファイル
honkit-base/layout.html at main · 1ft-seabass/honkit-base
絶賛調整中ではありますが、Honkit の基本的な HTML テンプレートとなるレイアウトファイル。book.json で指定した title や description が反映されます。
<!DOCTYPE HTML>
<html lang="{{ config.language }}" {% if page.dir == "rtl" %}dir="rtl"{% endif %}>
<head>
<meta charset="UTF-8">
<head prefix="og: https://ogp.me/ns# fb: https://ogp.me/ns/fb# article: https://ogp.me/ns/article#"></head>
<meta property="og:type" content="article">
<meta property="og:url" content="{{ file.path | replace('.md', '.html') }}">
<meta property="og:image" content="https://i.gyazo.com/800eb533b2b3a652c4e9973a62bb9f97.png">
<meta property="og:title" content="[{{ config.title | d("HonKit", true) }}] {{ page.title }}">
<meta property="og:description" content="{{ config.description }}">
<meta property="og:locale" content="{{ config.language }}">
<title>[{{ config.title | d("HonKit", true) }}] {{ page.title }}</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="description" content="{{ config.description }}">
<meta name="generator" content="HonKit {{ gitbook.version }}">
{% if config.author %}<meta name="author" content="{{ config.author }}">{% endif %}
{% if config.isbn %}<meta name="identifier" content="{{ config.isbn }}" scheme="ISBN">{% endif %}
{% block style %}
{% for resource in plugins.resources.css %}
{% if resource.url %}
<link rel="stylesheet" href="{{ resource.url }}">
{% else %}
<link rel="stylesheet" href="{{ resource.path|resolveAsset }}">
{% endif %}
{% endfor %}
{% endblock %}
{% block head %}{% endblock %}
</head>
<body>
{% block body %}{% endblock %}
{% block javascript %}{% endblock %}
</body>
</html>
頑張っているところとしては OGP をざっくり作っているところです。こうするとソーシャルメディア上で公開してもきれいにサムネイルが出ます。Slack で URL を紹介した時にも、サムネイルがきれいに出るのでがんばりました。
プラグインで簡単に設定できるのもありそうなんですが、その簡単な設定に脳のメモリが割けるか怪しいので手運用にしてます。とりあえず、いまは無難に動いています。
大事なのは OGP は最初に決めることですね。ソーシャルメディアや Slack で一度キャッシュされると、いつリフレッシュされるか悶絶するので注意です。あと、OGP の画像置き場がどこかに必要ですが、私の場合は Gyazo に置いています。
そのほか TIPS
課題点や、運用上はこうしているっていう話です。
プラグイン構成は定期的にチェック
Gitbook 時代から一定の人気があるので、こうしたいと思ったら調べてみるとめっちゃ勉強になります。
npm のほうで honkit- とか gitbook- で調べると色々出てきますし、こういうナレッジがさがせるのは Honkit のいいところです。設定でハンズオン数日前とかに孤軍奮闘したくない。
非公開したら PDF 提供にもできる
こちらの記事にありますが、全部のページをつなげて PDF にするっていう荒業ではあるものの、非公開後に PDF にもできます。授業が終わった後に、非公開にしなければならないケースや、資料そのものを納品しないといけないときに使う技です。
画像は全部 Gyazo へ置いてます
絵素材はあえて Gyazo へ置いてます。それで、資料へ配置するときは、その URL を引いています。自分は Gyazo 有料アカウントなので、ちょっとパワープレイ気味なところです。
こうやって URL でどこからも引けるようにしておくと、一部の資料を他で使ったりしても、Markdown 部分をコピーアンドペーストでいけるので汎用性が高いのでそうしています。
GitHub の同リポジトリ内に画像を置いておく手法はもちろんありますね。ただ、他で使うとなると GitHub の URL を引かないといけないので、ちょっと汎用性が悪いので、いまは避けています。移植する場所によっては画像が置きづらいケースもありますしね。
目次をいちいち作るのが面倒なのでなんとかしたい
Honkit は SUMMARY.md に書かないとビルドしてもページで登場してくれない仕様です。これは運用上うっかり公開されなくて良い面もあるのですが、自動化したいなと思うときもあるので、いずれうまくやたいところです。
GitBook の SUMMARY.md を自動生成する – へっぽこプログラマーの備忘録
Gitbook 時代からこういうのはあるみたいなので、何とかなりそうな気がしますが、自分のやりやすい手法だと自前で書いたほうがいい気もしています。
検索フィールドに引っ張られて、コンテンツ増やすと、どんどん書き出しファイルが増える
そうはいっても 50 ページくらい作っても、すごい待つわけではないので許容範囲ではあります。
これはデフォルトで入っている資料全体をいつでも検索できる検索フィールドのためです。検索できるようインデックス化が全ファイルで走るせいのようなんですが、書き出すページが増えれば、その分だけ増えます。
当たり前といえば当たり前の挙動なんですが、ほかの人のプラグイン構成をみていると検索フィールドをオフにしたり、インデックス化を抑制した検索フィールドプラグインを使っているところをお見受けするので、今度ナレッジを整えてみたいです。
ビルド忘れよくあるので GitHub Action 化したいのはある
はい。明示的に npm run build してコミットしろよ感はあるのですが、このあたり忘れやすいので GitHub Action で自動化したいところです。
とはいえ、そういう設定が増えると環境設定にしくじりやすいので横展開しにくくなる可能性はあるので、やりたいけれども、慎重にナレッジ整えたいところ。
たぶん文法チェックもいれればより強力というのはある
そう。技術書典などでお見掛けする文法チェック text-lint かけとくのはいいですよねえ。資料の品質が保ちやすくなるので、どこかで入れてみたいです。佳境に資料をガシガシ作っているときほど文章が怪しくなったり崩れたりするので大事。
おわりに
ということで、現情報告という感じですが、授業資料やハンズオン資料に使っている HonKit の設定がある程度整ったのでまとめてみました。実際、いま稼働して磨いているものですし、こうやってまとめてみると、今後良くしたい点や、自分なりのこだわりポイントが見えてきますね！