Getting Started | mdhelpDocs

Getting Started

Getting Started

MDHELPを使って簡単な日英言語のヘルプを作成します。HUGOおよびHTML Help Workshopのインストールを済ませていることを前提とします。

© 2020 - 2021 mochimo.


Getting Started | mdhelpDocs

Getting Started

準備

HUGOとHTML Help Workshopのインストールがまだであれば、まずはインストールを行います。その後、hugo.exeおよびhhc.exeにPATHを通しておきます。

インストール

新しいプロジェクトを作成します。ここではmyhelpという名称としてみましょう。

hugo new site myhelp
cd myhelp

MDHELPテーマをインストールする

HUGO公式ドキュメントに沿ってgitでテーマを取得します。

git init
git submodule add https://github.com/mochimochiki/mdhelp themes/mdhelp

gitを利用しない場合、最新のzipもしくは任意のReleaseをダウンロード・解凍し、themes\mdhelpに配置してください。

必要なファイルをコピーする

以下のコマンドでヘルプのビルドに必要なツール類とconfigをコピーしてmyhelpプロジェクトに配置します。また、デフォルトのconfig.tomlは削除しておきます。

xcopy /s themes\mdhelp\exampleSite\config config\
xcopy /s themes\mdhelp\exampleSite\CI CI\
rm config.toml

最初のサイトの作成

config.tomlの編集

config\_default\config.tomlを開き、以下の行をコメントアウトもしくは削除します。

themesdir = "../.."

ヘルプのタイトルをMyHelpに変更します。各言語のtitleの設定を以下のように編集します。

[languages.jp]
  ...
  title = "MyHelp"
  ...
[languages.en]
  ...
  title = "MyHelp"
  ...

その他のconfigパラメータについてはヘルプの構成およびHUGO公式ドキュメントなどを参照してください。

トップページの作成

contentディレクトリ下にjp,enディレクトリを作成します。

mkdir content\jp
mkdir content\en

jpおよびen下に_index.mdファイルを作成して以下のように編集し、文字コードUTF-8で保存します。

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

# My Help

My Help サイトです。

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

# My Help

This is My Help.

記事の作成

次に記事を作成します。jpおよびen下にHello.mdを作成して以下のように編集します。

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

## Hello

こんにちは。

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

## Hello

Hello World !
Note
記事のファイル名はASCII文字で記述してください。日本語ファイル名をつけるとヘルプが正常にビルドされません。

サイトをプレビューする

ここまでで一度プレビューしてみましょう。以下のコマンドを実行し、ブラウザでhttp://localhost:1313/およびhttp://localhost:1314/にアクセスします。

hugo server

Hello.mdを適当に編集して保存してみます。LiveReloadがかかり、ブラウザ上のプレビューも更新されることを確認します。原稿はこのようにプレビューで執筆していきます。

ディレクトリと2番目の記事を追加する

jp下にsecond_contentディレクトリを作成し、_index.mdを作成して以下のように編集します。

---
title: "Second Chapter"
chapter: true
weight: 20
---

# Second Chapter

2番目のチャプターです。
Note
ディレクトリ名はASCII文字で記述してください。日本語を使用するとヘルプが正常にビルドされません。

またsecond.mdを作成して以下のように編集して保存します。

---
title: "2番目の記事"
weight: 10
---

## 2番目の記事

こんにちは。これは2番目の記事です。

再度プレビューを表示し、2番目の記事が表示されることを確認します。

hugo server

ヘルプの作成

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

.\CI\build.bat chm
  • myhelp\public_chm\jp\MyHelp.chm
  • myhelp\public_chm\en\MyHelp.chm

が成果物のヘルプです。確認してみましょう。


ヘルプの構成 | mdhelpDocs

ヘルプの構成

ヘルプを構成するためのconfig.tomlの主な項目の説明をします。HUGO公式ドキュメントも合わせて参照してください。

Config

publishDir

出力ディレクトリです。public_(environment名)と設定します。例えばchmディレクトリに配置したconfig.tomlではpublic_chmと設定します。

ignoreFiles

無視するファイル。エディションごとで出力ディレクトリやファイルを変更する場合に使用します。例えばignoreFiles = ["ignore"]とするとignoreの含まれるディレクトリ・ファイルがビルド対象外（ヘルプの目次作成からも対象外）になります。

Config.params

[params]以下に設定する設定値です。

author

フッターに表示されるauthorを設定します。

copyRightYear

フッターに表示されるCopyRightの年を設定します。

isCHM

CHMかどうか。この設定は通常Webサイト用のconfig.tomlではfalseとし、HTML Help生成用のconfig.tomlではtrueにします。テンプレートでWebサイトとヘルプ生成時で処理を分ける際に使用します。

custom_css

独自のcssを利用する場合に設定します。例えば/static/css/custom.cssにcssファイルを配置しcustom_css = ["/css/custom.css"]とするとcustom.cssが適用されます。

custom_js

独自のjavascriptを利用する場合に設定します。例えば/static/js/custom.jsにjsファイルを配置した場合、custom_js = ["/js/custom.js"]とするとjavascriptが適用されます。

showIfs

ShowIf/HideIfフロントマター/ショートコードで表示する条件の一覧。

showIfs = ["editionA", "editionB"]

例えば上記のように設定した場合、.mdファイルで以下のブロックは表示されます。

{{% ShowIf editionA %}}
ここにeditionAの場合に表示するコンテンツを記述。
{{% /ShowIf %}}

以下のブロックは表示されません。

{{% HideIf editionA %}}
ここはeditionAのみ非表示とする。
{{% /HideIf %}}

記事単位では以下のようにフロントマターを書いている場合、その記事はchmに含まれます。一つのエディションだけであってもリスト形式（["editionA"]）で書く必要があります。

---
title: editionAの説明
ShowIf: ["editionA"]
---

---
title: editionA以外はこの説明
HideIf: ["editionA"]

本設定について詳しくはエディションを参照してください。

Config.languages

[languages] - [languages.jp] などに設定する設定値です。

title

各言語のヘルプタイトルです。ヘルプのファイル名称およびウィンドウタイトルに利用されます。

フロントマター

記事のフロントマターでの設定は以下のとおりです。

hideHelpTOC

ヘルプの目次のチャプター（ツリーの本アイコン部分）として表示するかどうか。デフォルトでは表示されます。隠す場合はチャプターの_index.mdのフロントマターに以下のようにhideHelpTOCを追加します。

hideHelpTOC: true


HTML Helpの構成ファイル | mdhelpDocs

HTML Helpの構成ファイル

HTML Help をビルドするには以下のような構成ファイルが必要です。

ファイル | 説明
project.hhp | ヘルプのプロジェクトファイル。オプションなどを定義。
toc.hhc | 目次定義ファイル
Map.h | HelpID定義ファイル。

mdhelpはこれらの構成ファイルを基本的に自動で生成します。ただし、プログラムからヘルプIDを指定して特定ページを呼び出すためにヘルプのAPI情報を定義する場合は、自前でMap.hを準備する必要があります。mdhelpは/static/Map.hを使用してヘルプをコンパイルするため、/static/Map.hにマップファイルを作成します。

Map.h を作成する

mdhelpのbuild.batでヘルプをビルドすると、publishDirに成果物のヘルプファイルと共にMapTemplate.hが生成されます。これはヘルプのすべてのページのHelpIDのテンプレートを含みます。プログラムからヘルプのページを呼び出すためにMap.hを用意する場合、このテンプレートの各IDに対して一意の数値をふり、/static/Map.hとして保存してから、再ビルドしてください。

Note
この作業はページが増えた際にも必要になります。増えたページのID分を/static/Map.hに足します。

project.hhp をカスタマイズする

project.hhpはHUGOのテンプレートの仕組みで生成しています。そのため通常のテンプレートと同様/themes/mdhelp/layouts/index.hhpを/layouts/index.hhpにコピーして編集すれば自由にカスタマイズすることができます。


ショートコード | mdhelpDocs

ショートコード

mdhelpテーマで使用できるショートコードの一覧です。これらはビルドされる HTML Help に対しても有効です。

ShowIf

config.tomlのshowIfsで列挙されている場合に描画する部分を指定します。以下はshowIfs = ["editionA"]とした場合に描画されるブロックです。

{{% ShowIf editionA %}}
ここにxxxをサポートする場合に表示するコンテンツを記述。
{{% /ShowIf %}}

構成も参照してください。

HideIf

config.tomlのshowIfsで列挙されている場合に描画「しない」部分を指定します。

{{% HideIf editionA %}}
ここはeditionAでは表示したくない。
{{% /HideIf %}}

構成も参照してください。

note

注記です。以下のようにnoteショートコードで囲まれた部分が注記としてレンダリングされます。

{{% note %}}
ここに注記文章を記載
{{% /note %}}
Note
ここに注記文章を記載

note (title)と言う形式で、引数にタイトルを指定することもできます。note内部にMarkdownを書くことも可能です。

{{% note 注記 %}}
ここに注記文章を記載

* markdownも記載可能
  * 箇条書きレベル2
* 箇条書きレベル1
{{% /note %}}
注記

ここに注記文章を記載

  • markdownも記載可能
    • 箇条書きレベル2
  • 箇条書きレベル1

include

高度な表をincludeする（セル結合/Markdown/幅指定/ヘッダー有無指定）

csvファイルのincludeでは、Markdownよりも高度な表を描画することができます。

rich.csv

{{< include
      src="./rich.csv" # sourceファイルのパス
      class="gray"      # tableに付加するclass属性。未指定/simple/gray
      markdown=true     # trueにした場合表内部のMarkdownをレンダリング。初期値false
      merge=true        # trueにした場合空セルを上のセルで結合。初期値false
      head=true         # trueにした場合1行目をヘッダーとみなす。初期値true
      width="90%"       # tableのwidth属性を設定。
      width-ratio="5%-10%-70%-15%" # tableの列幅の比率を-区切りで指定。"*"はauto。
>}}
id | カテゴリ | 名称 | 備考
001 | 果物 | りんご
002 みかん
  • せとか
  • 甘平
003 | ぶどう | 巨峰
004 お菓子 ポテトチップス
  • うすしお
  • のりしお
005 飴
  • みかん
  • ぶどう


エディション | mdhelpDocs

エディション

内容が微妙に異なるヘルプのファミリーを生成する必要がある場合、HUGOのConfiguration Directoryの仕組みを利用してエディションを作り分け、構成や記事内容を切り替えてビルドできます。

エディションのconfigを作成する

/config/chm_otherというディレクトリを作成し、/config/chm/config.tomlをコピーして編集することで簡単にchm_otherエディションを作成することができます。それぞれのエディションのconfigはヘルプの構成に沿って編集します。以下では主要な設定変更について説明します。

タイトル

ヘルプのタイトルがエディションごとに違う場合、各言語のtitleを設定します。

[languages]
  [languages.jp]
    title = "other"

特定記事・特定要素の表示/非表示を切り替える

ShowIf,HideIfショートコード/フロントマターと共にshowIfsを使用することで表示/非表示を切り替えます。

[params]
  showIfs = ["editionA"]

この場合、.mdの記事で以下のように記載した要素が表示されます。

{{% ShowIf editionA %}}
ここにeditionAをサポートする場合に表示するコンテンツを記述。
{{% /ShowIf %}}

以下のように記載し作用素は表示されません。

{{% HideIf editionA %}}
ここにeditionAの場合に非表示とするコンテンツ。
{{% /HideIf %}}

記事単位では以下のようにフロントマターを書いている場合にchmに含まれます。一つのエディションだけであってもリスト形式（["editionA"]）で書く必要があります。HideIfも同様です。

---
title: editionAの説明
ShowIf: ["editionA"]
---

ビルドする

エディションを指定してビルドするには、引数にエディションを指定します。例えばchm_otherエディションをビルドするには以下のように指定します。

.\CI\build.bat chm_other


CIでヘルプを自動ビルドする | mdhelpDocs

CIでヘルプを自動ビルドする

CI環境からヘルプをビルドする際に利用できる情報を説明します。

ビルド

CI環境からはbuild.batをエディションの引数付きで呼んでください。以下はchm_your_editionの例です。

.\CI\build.bat chm_your_edition

ビルドの内部処理は以下のようになります。

  1. HUGOで--environmentにエディションを指定してWebサイトをビルド
  2. jp下の*.hhp, *.html, *.hhcファイルをすべてSJISに文字コード変換
  3. hhc.exeでjp,enのヘルプをビルド

成果物

成果物であるHTMLヘルプはpublishDirの設定に従って出力されます。 publishDir = "public_chm_your_edition" の場合、以下がヘルプの出力先になります。

/public_chm_your_edition/jp/(helpTitle).chm
/public_chm_your_edition/en/(helpTitle).chm

UTF8からSJISに変換できない文字のリスト

HUGOはUTF8のWebサイトを生成しますが、HTMLHelpで日本語を扱うためにはSJIS(Windows CP932)へ変換する必要があります。変換はbuild.batの処理で行われますが、SJISに対応文字がなく変換できなかった文字については、build.batと同じディレクトリのunknonw_(edition).logに記録されます。

置換できない文字の例

SJISの対応文字に置換できない文字は"?“で置換されます。例えば以下の文字はHTML Helpでは”?“となります。

30F7 ?
30F8 ?
30F9 ?
30FA ?

カスタムマッピング

変換できない文字をSJISの特定文字にマッピングするには、/CI/UTF8toSJISConverter.csのFallbackメソッドのswitch文を編集します。

エラー処理

build.batはエラー時にエラーコード1を返します。バッチから呼ぶ場合、例えば以下のようにエラー処理できます。

.\CI\build.bat chm_your_edition
if not %errorlevel% == 0 exit /B 1


Content1s | mdhelpDocs

Content1s

© 2020 - 2021 mochimo.


content1_page1 | mdhelpDocs

content1_page1

Test

content1 ページです。

include test

この文書はincludeされています。

Note
注記もincludeできます


ヘルプの構成 | mdhelpDocs

ヘルプの構成

Configuration

ヘルプの構成を変更するための各種機能を説明します。


mdhelpDocs

MDHELP

MDHELP

MDHELP は HTML Help (.chm) のヘルプを生成することを目的としたHUGOのテーマです。

本ドキュメントは/exampleSiteをmdhelpでビルドしたものです。同じドキュメントのHTML Help版はこちらです。

Note

mdhelpDocs.chmを開いてもコンテンツ部分が白い表示となる場合は、mdhelpDocs.chmを右クリックしてプロパティを開き、[全般]-[セキュリティ]で

セキュリティ: このファイルは他のコンピューターから取得したものです。このコンピューターを保護するため、このファイルへのアクセスはブロックされる可能性があります。

の項目を許可してください。