Hugoを利用してMarkdownからCHM形式のヘルプを生成する

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

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

そんなCHMヘルプは[HTML Help Workshop](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/htmlhelp/microsoft-html-help-downloads)などを使用してhtmlのコンテンツをコンパイルすることで生成できるが、htmlを直接編集するのは辛いので、Markdownから記事のhtmlを生成、ついでにヘルプ生成のために必要な諸々の構成ファイルも自動生成して一気にCHM形式にコンパイルまでできないか、と検討してみた。

# Hugoを利用する

[Hugo](https://gohugo.io/)はいわゆる静的サイトジェネレータの一種だ。Markdownで書いた記事をWebサイトに変換してくれるツールで、Qiitaにも多くの紹介記事がアップされている。例えば[こちら](https://qiita.com/peaceiris/items/ef38cc2a4b5565d0dd7c)。

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

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

# mdhelp テーマ

そんなモチベーションで、Hugoのテーマ[mdhelp](https://github.com/mochimochiki/mdhelp)を作成してみた。以下簡単に紹介する。詳しくは[mehelp Docs](https://mochimochiki.github.io/mdhelp/jp/)を参照。

### 動作確認環境

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

## ざっくりとした使い方

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

[HUGO](https://gohugo.io/)と[HTML Help Workshop](https://www.microsoft.com/en-us/download/details.aspx?id=21138)をインストールし、`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](https://github.com/mochimochiki/mdhelp/archive/master.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 公式ドキュメント](https://gohugo.io/getting-started/quick-start/)
* [まくまく Hugo/Go ノート](https://maku77.github.io/hugo/)

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

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

## 文字コード

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

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

```config.toml
htmlcharset = "Shift_JIS"
```

```baseof.html
<meta charset="{{ .Site.Params.htmlcharset }}">
```

## CSS3やhtml5は使えない

ヘルプは内部的には[IE7(!!)のエンジンでレンダリング](https://weblog.west-wind.com/posts/2012/feb/15/make-your-chm-help-files-show-html5-and-css3-content)されているらしく、html5/css3はおろかcss2.1も満足に利用できない。`:before`や`:after`は使えないので、それを考慮する必要があった（というより極々簡易的なcssにとどめている）。