Giter Club home page Giter Club logo

mdhelp's Introduction

mdhelp

mdhelpはHTML Help(.chm)のヘルプを生成することを目的としたHUGOのテーマです。テーマ本体に加え、HTML Help生成に利用するツールなどを含んでいます。HTML Helpの生成には別途HTML Help Workshopが必要です。

詳しい使い方はmdhelp Docsを参照してください。

使い方

前提条件

  1. HUGOをダウンロード・インストールし、hugo.exeにPATHを通しておきます。
  2. Microsoft HTML Help DownloadsからHtmlhelp.exeをダウンロード・インストールし、hhc.exeにPATHを通しておきます。

Clone

git clone https://github.com/mochimochiki/mdhelp.git
cd mdhelp

ExampleSiteをコンパイル

以下のバッチを実行すると2種類のconfigでHUGOのビルド及びヘルプの生成が行われます。

.\exampleSite\CI\build.bat

以下が成果物です。

  • .\exampleSite\public_chm\jp\mdhelp.chm
  • .\exampleSite\public_chm\en\mdhelp.chm

制約

原稿のファイル名

原稿のmdファイル名は英数字とパーセントエンコーディングされない記号のみ対応しています。日本語など、URLがパーセントエンコーディングされるファイル名の場合、chmコンパイル時にエラーが発生します。

mdhelp's People

Contributors

mochimochiki avatar

Stargazers

 avatar  avatar

Forkers

anima-otheros

mdhelp's Issues

UTF-8 to SJIS(Windows-31J) の仕組みを実装する

  • hhp, hhcはSJISでないとコンパイル時に文字化けする。HUGOでビルドしたhhp/hhcをWindows-31J(SJIS)に変換する仕組みが必要。
  • 原稿から生成されたhtmlはUTF-8でもコンパイル可能だが、HTML Helpの全文検索などで文字化けするため原稿のhtmlも変換したほうが良い。
  • htmlにも対応する場合、UTF8 to SJIS での文字化け発生をできる限り抑える必要がある。
  • metaタグなどの対応も必要

exampleSiteの原稿を整える

以下のような点を踏まえた原稿サンプルを作成する

  • jp/en
  • markdown-showcase
  • 画像/gifなどを含む
  • エディションによって含まないセクションがある
      • #5, #6 の仕組みで記事やコンテンツの表示/非表示切替
  • weightによってセクションと記事の位置を操作

Include csv with a relative path

include は _includeディレクトリからしかできなかった。markdownファイルについてはそうしないと部品ファイルまでレンダリングされてしまうためこれで問題ないが、csvについては原稿の横にcsvファイルを置いて読み込みたい場合がある(マスターデータではなく、単に原稿に関連づいた大きな表を書きたい場合など)。よってincludeの仕様を以下のように変更する

.mdファイルからの相対パスで指定されたcsvが見つかった場合、そのcsvをincludeする
見つからなかった場合、_includeディレクトリからincludeする

ShowIfをフロントマターで使えるようにする

あるエディションでのみヘルプに含めたいファイルがある場合に、現状では他のすべてのエディションのconfig.tomlのignorefilesにそのファイルを無視するための実装が必要。そうではなく、原稿自体にShowIfで特定エディションだけで表示するとできたほうがメンテコストが下がる。また、文中ではShowIfショートコードが使えるので、それとの整合性も高い。

原稿の出力抑制自体は難しいと思われるため、ヘルプおよびサイトの目次リストから消してヘルプビルド時に含まれなくなる方向で検討する。

Webヘルプ用のConfigを用意する

chm形式と同時に通常のWebヘルプサイトとしてもそのまま使用可能であるように、シンプルかつ必要十分なものを用意しておきたい。執筆中のプレビューもこちらで行う

英語版を作成する

build.batは日本語版のみを生成する設定になっている。英語版も同時に生成するようにする。
hhp/hhcが日本語固定となっている。configから設定を流し込むようにする。

MAPとAlias生成の仕組みを作る

できればAlias.hも自動生成したいが、IDがビルドで変わってしまうと困る。前回のにマージする形式でIDだけ埋めればいい状態のテンプレートを作るくらいか。

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.