CHM形式のヘルプをMarkdownで書きたい

今どきCHM形式のヘルプ（HTML Help）を作成する需要がどれほどあるかは分からないが、「インターネットに接続できない環境にあってマニュアルを提供する手段」として、ファイル1つでWindows環境であればデフォルトでほぼ確実に動作し、プログラムから特定ページを指定して開ける、というのは中々代替手段もなく、未だ現役なレガシーだという気もする。

そんなCHMヘルプはHTML Help Workshopなどを使用してhtmlのコンテンツをコンパイルすることで生成できるが、htmlを直接編集するのは辛いので、Markdownから記事のhtmlを生成、ついでにヘルプ生成のために必要な諸々の構成ファイルも自動生成して一気にCHM形式にコンパイルまでできないか、と検討してみた。

Hugoを利用する

Hugoはいわゆる静的サイトジェネレータの一種だ。Markdownで書いた記事をWebサイトに変換してくれるツールで、Qiitaにも多くの紹介記事がアップされている。例えばこちら。

高速かつ強力なテンプレート機構を備えており、Markdown->htmlだけでなく、自由な形式のファイルをテンプレートに沿って生成できるため、これを使ってMarkdownをhtmlに変換しつつ、ついでに.hhp,.hhcなどのヘルプの構成ファイルを生成すれば目的が達成できそうだ。

Hugoを使うことでCHM生成の流れの中で一度Webのマニュアルサイトを生成することになるので、いずれはCHMからWebのマニュアルへ、という流れへスムーズに繋がるのも魅力的だ。

mdhelp テーマ

そんなモチベーションで、Hugoのテーマmdhelpを作成してみた。以下簡単に紹介する。詳しくはmehelp Docsを参照。

動作確認環境

Windows 10 Pro (JP)
Powershell 5.1
hugo v0.73.0
HTML Help Workshop 4.74.8702

ざっくりとした使い方

1. Hugo と HTML Help Workshop のインストール

HUGOとHTML Help Workshopをインストールし、hugo.exeおよびhhc.exeにPATHを通しておく。

2. mdhelp のインストール

適当なディレクトリでコマンドプロンプトから以下を実行し、Hugoのサイトを新規作成する。myhelpは好きな名前で。

hugo new site myhelp
cd myhelp
git init
git submodule add https://github.com/mochimochiki/mdhelp themes/mdhelp

gitを使用せず、zipを/myhelp/theme/mdhelpに展開しても良い。

3. ディレクトリ構成

続いて必要なファイルをexampleSiteからコピーする。また原稿置き場を作っておく。

xcopy /s themes\mdhelp\exampleSite\config config\
xcopy /s themes\mdhelp\exampleSite\CI CI\
rm config.toml
mkdir content\jp
mkdir content\en

4. config.tomlの編集

config\_default\config.tomlを開き、以下の不要な行を削除する。

config.toml

themesdir = "../.."

5. トップページの作成

content\jp\_index.mdおよびcontent\en\_index.mdを作成し、UTF-8で以下のように編集する。

_index.md(jp)

---
title: "My Help"
---

# My Help

My Help サイトです。

_index.md(en)

---
title: "My Help"
---

# My Help

This is My Help.

6. 記事の作成

content\jp\Hello.mdおよびcontent\en\Hello.mdを作成し、UTF-8で以下のように編集する。

Hello.md(jp)

---
title: "Hello"
weight: 10
---

## Hello

こんにちは。

Hello.md(en)

---
title: "Hello"
weight: 10
---

## Hello

Hello World !

7. Hugoでプレビューする

myhelpディレクトリで以下のコマンドを実行し、hugoのプレビューサイトを起動する。http://localhost:1313/にアクセスして記事のプレビューを確認する。

hugo server

8. ヘルプのコンパイル

Ctrl+C でhugoのプレビューを終了し、以下のコマンドを実行してヘルプをコンパイル。

.\CI\build.bat chm

myhelp\public_chm\jp\MyHelp.chm
myhelp\public_chm\en\MyHelp.chm

が成果物のヘルプだ。

Hugoに慣れる

ヘルプのコンパイル以外はHugoそのものの機能のため、Hugoの知識があったほうが良い。個人的には以下のサイトが非常に参考になった。

テーマ作成時に検討したこと

当初はHugoがほぼ全部やってくれるんだからすぐだろう・・・と思っていたが、いくつか検討が必要だった点がある。もし同じようなテーマを作成をする際には参考になるかもしれない。

文字コード

HugoはMarkdown原稿も、生成するhtmlもUTF-8が前提だ。しかし残念なことにHTML HelpはUTF-8を扱ってくれない。そこでHugoの出力するhtmlファイルをすべてUTF-8->SJISへ変換するpowershellスクリプトおよびc#クラスを作成し、文字コードをSJISに変換する処理をヘルプコンパイル前に差し込んでいる。UTF-8からSJISへの変換がうまくいかない例があるため、これらの文字についてはできる限り似たようなSJIS文字に変換するようにし、それ以外の変換できない文字はログに記録するようにした。

またhtmlの<meta>タグについてはHugoのテンプレートを利用してconfig.tomlから文字コードを流し込むようにし、Webマニュアル生成時にはUTF-8,CHMヘルプ生成時にはShift_JISとなるようにした。