DocFXでPDF作成

2019/08/15 DocFX
PDFに関してはなんとなくまだまだ発展途上の気がします。

wkhtmltopdfのインストール

第一の難関でした。
インストールし、環境変数にPathも追加しコマンドプロンプトでwkhtmltopdf -Vするとちゃんとバージョンが表示されるにも関わらず、下記のエラーが出てPDFが作成されない。
(環境はWin10でVS2019です)
wkhtmltopdf is a prerequisite when generating PDF. 
Please install it from https://wkhtmltopdf.org/downloads.html 
and save the executable folder to %PATH% first. 
Alternatively you can install it from https://chocolatey.org 
with `choco install wkhtmltopdf`.
ユーザーの環境変数ではなくシステムの環境変数に追加してもダメ。
VSを管理者として実行してみたらエラー解消。
一度解消すると、その後普通にVS起動してもエラー出ず。

pdfフォルダを作成し、中にtoc.ymlを置く

toc.yml

- name: Articles
  href: ../articles/toc.yml
- name: Api Documentation
  href: ../api/toc.yml

docfx.jsonにPDF関連のセクション追加

wkhtmltopdfのオプション

wkhtmltopdfのオプション一覧はこちら
docfx.jsonで指定する場合は"wkhtmltopdf":だけでなく"additionalArguments":が必要。

ページ番号を表示させる場合の例

...
"pdf": {
  "wkhtmltopdf": {
    "additionalArguments": "--footer-center [page]"
  },
  "content": [
...

PDF用CSSの調整

デフォルトのままのCSSだとIMPORTANTやWARNINGなどのデザインが崩れています。
しかも日本語化したはずのIMPORTANTやWARNINGもそのまま表示されています。
docfx pdf alert

デフォルトのPDF用テンプレートをエクスポート

こちらでWebサイト用のテンプレートをエクスポートしたのと同様、PDF用のデフォルトテンプレートをエクスポート。
docfx template export pdf.default
エクスポートが成功すると、pdf.default フォルダが追加されます。
pdf.default

カスタムテンプレートの作成

  • fontsフォルダがエクスポートしたpdf.defaultにはなかったので、defaultからコピー。
  • main.cssは元々空なので、エクスポートしたものをコピーしなくても同じ名前で作成した方が文字コードUTF-8になるかも。
  • token.json:唯一pdf.defaultからコピー。
docfxpdf025.png

docfx.jsonの編集

"pdf": {
  "template": [
    "pdf.default",
    "templates/pdf"
  ],

main.cssに追記

padding入れたり、アイコン(glyphicons)のコード変えたり(Web版と違うことに気づいた自分えらい)してかなり近づきましたが、ボーダーとフォントサイズが違いそう。
docfx pdf alert

表紙をつける

pdfフォルダ内にcover.mdを追加

docfxcover010.png

cover.mdに表紙用のスタイル適用

---
documentType: cover
---
# The real cover page title

表紙用スタイルをカスタマイズ

cover.html.primary.tmplを上書き
docfxcover020.png


詳しくはこちら

TOC(目次・Table of Contents)

下記の右側部分。デフォルトで作成される。
docfxpdf070.png

ページ番号が表示されないのは現在の仕様。ulタグのループになっている。
ページ番号表示しようとしたらテーブルにする気がする。

wkhtmltopdfのtocはページ番号付き。ただし最新の安定版ではバグによりtocが作成されない。

outline(しおり・ブックマーク)

DocFXのオプション

DefaultOutlinetoc.ymlを元にブックマーク作成?(デフォルト)
WkDefaultOutlineHTML内のhXを元にブックマーク作成
NoOutlineブックマークを作成しない
なぜかデフォルトのDefaultOutlineのリンクが変。
タイトルとジャンプ先ずれる。
スクロール位置によってジャンプ先が異なるような気もして安定しない。
似たような報告がされているけれど既にClose済み。Nugetのバージョンによるものかもしれません。
WkDefaultOutlineを使うかNoOutlineにする。

WkDefaultOutline

"pdf": {
  "outline": "WkDefaultOutline",
ジャンプ先はきれいに安定するようになりましたが…
docfxpdf050.png

「重要」「警告」などはh5で囲まれていたはず。勘弁してください状態。
試しにアラートの前にh2とh3を追加しアウトラインを3層までに制限してみました。
"pdf": {
  "outline": "WkDefaultOutline",
  "wkhtmltopdf": {
    "additionalArguments": "--footer-center [page] --outline-depth 3"
  },
docfxpdf060.png

これで使い物になるかどうかは使う人の判断で(^^;)。
※hXタグから自動で作成されるため、docfx.json内のtocTitleオプションも無視されます。
「Table of Contents」を日本語にしたい場合は、テンプレート(toc.html.tmpl)を日本語化しましょう。
docfxpdf070.png

OK キャンセル 確認 その他