HonkitをPDFで出力したい
Honkit、便利ですよね。簡単にPDFで出力できたらもっと便利ですよね。
それ、Dockerですぐにできます
Honkitのディレクトリで、以下のコマンドを実行するだけでoutput.pdfが生成されるんです!
docker run --rm -v .:/honkit nishidemasami/markdown-docs:v1.2.1 npx honkit pdf ./ ./output.pdf
TL;DR
以下のリポジトリで実践しています。これを見れば一目でわかります。
ドキュメントをHonkitで作ってPDFに出力する
とりあえず最小構成で動かしてみます。と言っても白紙が出てもちゃんと動いているかよくわからないので、今回は試しにPlantUMLでAWSのサンプルのAWS構成図を書いてみます。
ファイル構成
まずは4つのファイルを作成します。
内容は以下の通りです。
Honkitの設定ファイル
Honkitの設定ファイルです。
さらに詳しい設定をしたい場合は以下サイトから設定値を確認してください。PDFの余白の幅とかも変えられますよ!
https://honkit.netlify.app/config.html
{
"plugins": [
"uml"
],
"uml": {
"charset" : "UTF-8"
},
"language": "ja"
}
READMEページ
# Honkitで書いたドキュメントをDockerでPDFに変換する
このコマンドでできます
```bash
docker run --rm -v .:/honkit nishidemasami/markdown-docs:v1.2.1 npx honkit pdf ./ ./output.pdf
```
目次ページ
# 目次
* [Honkitで書いたドキュメントをDockerでPDFに変換する](README.md)
* [PlantUmlテスト](plantuml.md)
PlantUMLサンプルページ
# PlantUmlテスト
```uml
@startuml
'Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
'SPDX-License-Identifier: MIT (For details, see https://github.com/awslabs/aws-icons-for-plantuml/blob/master/LICENSE)
!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v14.0/dist
!include AWSPuml/AWSCommon.puml
!include AWSPuml/Groups/all.puml
!include AWSPuml/Compute/LambdaLambdaFunction.puml
!include AWSPuml/General/Documents.puml
!include AWSPuml/General/Multimedia.puml
!include AWSPuml/General/Tapestorage.puml
!include AWSPuml/General/User.puml
!include AWSPuml/MediaServices/ElementalMediaConvert.puml
!include AWSPuml/MachineLearning/Transcribe.puml
!include AWSPuml/Storage/SimpleStorageService.puml
skinparam shadowing false
' define custom group for Amazon S3 bucket
AWSGroupColoring(S3BucketGroup, #FFFFFF, AWS_COLOR_GREEN, plain)
!define S3BucketGroup(g_alias, g_label="Amazon S3 bucket") AWSGroupEntity(g_alias, g_label, AWS_COLOR_GREEN, SimpleStorageService, S3BucketGroup)
!procedure $stepnum($number)
<back:black><color:white><b>$number</b></color></back>
!endprocedure
' Groups are rectangles with a custom style using stereotype - need to hide
hide stereotype
skinparam linetype ortho
skinparam rectangle {
BackgroundColor AWS_BG_COLOR
BorderColor transparent
}
rectangle "$UserIMG()\nUser" as user
AWSCloudGroup(cloud){
RegionGroup(region) {
S3BucketGroup(s3) {
rectangle "$MultimediaIMG()\n\tvideo\t" as video
rectangle "$TapestorageIMG()\n\taudio\t" as audio
rectangle "$DocumentsIMG()\n\ttranscript\t" as transcript
user -r-> video: $stepnum("1")\lupload
video -r-> audio
audio -r-> transcript
}
rectangle "$LambdaLambdaFunctionIMG()\nObjectCreated\nevent handler" as e1
rectangle "$ElementalMediaConvertIMG()\nAWS Elemental\nMediaConvert" as mediaconvert
rectangle "$TranscribeIMG()\nAmazon Transcribe\n" as transcribe
video -d-> e1: $stepnum("2")
e1 -[hidden]r-> mediaconvert
mediaconvert -[hidden]r-> transcribe
mediaconvert -u-> audio: $stepnum("3")
transcribe -u-> transcript: $stepnum("4")
StepFunctionsWorkflowGroup(sfw) {
rectangle "$LambdaLambdaFunctionIMG()\nextract audio" as sfw1
rectangle "$LambdaLambdaFunctionIMG()\ntranscribe audio" as sfw2
e1 -r-> sfw1: Start\nExecution
sfw1 -r-> sfw2
sfw1 -u-> mediaconvert
sfw2 -u-> transcribe
}
}
}
@enduml
```
そしてこのコマンドを実行します。
docker run --rm -v .:/honkit nishidemasami/markdown-docs:v1.2.1 npx honkit pdf ./ ./output.pdf
めでたくoutput.pdfファイルに、3枚ペラのPDFファイルが出力されました!
このDockerの中ではなにをやっているの?
このnishidemasami/markdown-docs:v1.2.1
コンテナではなにをやっているのでしょうか?
詳細は上記のリポジトリで公開していますが、中身はこれだけです。
FROM debian:12-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN apt update && \
apt install calibre openjdk-17-jre-headless nodejs npm graphviz fonts-noto-cjk -y && \
groupadd -g 1000 honkit && useradd -m -d /home/honkit -s /bin/bash -u 1000 -g 1000 honkit
USER honkit
RUN mkdir ~/.npm-global && \
npm config set prefix '~/.npm-global' && \
echo export PATH=~/.npm-global/bin:$PATH >> ~/.profile && \
. ~/.profile && \
npm install -g honkit gitbook-plugin-uml
WORKDIR /honkit
いろいろ入れているのは、主にhonkitを動かすためのnpmとnodejs、PDFを変換するためのcalibreと、PlantUMLを実行するためのJDKとgraphviz、それから日本語フォントです。
それからhonkitユーザでhonkitをグローバルインストールしています。
ちなみに以前はCalibreのバージョンが古くて公式サイトからわざわざ取得してこないといけませんでしたが、Debian12ではcalibreのバージョンが6.26.0に上がっているので、そのまま使えます。感謝。
おわかりの通り、gitbook-pluginがgitbook-plugin-umlしか入っていないので、他に必要なプラグインがあればnpm installして各自入れてください。
mainブランチにpushされるたびにGitHub ActionsでPDFとHTMLを生成してReleaseしてGitHub Pagesで見れるようにする
応用として、mainブランチにpushされるたびにDockerでPDFを生成してReleaseするGitHub Actionsを作ってみます。
GitHub Pagesで見れるようにHTMLも生成しています。
name: Release PDF and Public GitHub Pages
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- name: Checkout
uses: actions/checkout@v3
- name: chmod for github actions docker
run: chmod -R 777 .
- name: Generate PDF
run: docker run --rm -v .:/honkit nishidemasami/markdown-docs:v1.2.1 npx honkit pdf ./ ./output.pdf
- name: Upload PDF
uses: actions/upload-artifact@v3
with:
name: documents
path: ./output.pdf
- name: Release
uses: softprops/action-gh-release@v1
with:
name: PDF Release
tag_name: pdf_relrase
generate_release_notes: true
files: ./output.pdf
- name: Generate pages
run: docker run --rm -v .:/honkit nishidemasami/markdown-docs:v1.2.1 npx honkit build
- name: Push to gh-pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_branch: gh-pages
publish_dir: _book/
これで、GitHubでドキュメントを管理して、いつでもPDFやGitHub Pagesで見れるようになりました!
まとめ
便利すぎるものを便利すぎるもので動かした結果、あまりにも便利すぎることになった