Hugo と Asciidoc で静的サイトの構築を行うためのスケルトンプロジェクトです。
日本語を扱う設定といろいろと制約のある Hugo との連携をそれっぽく実現しています。
AsciiDocから、PlantUMLやLatexの画像を含むサイトの生成、Github Pagesでの公開までを Github Actions で行います。
また、ローカルでの環境を VS Code + Remotecontainers で簡単に作れたり、PDFの生成も簡単に作成できます。
VS Code + Remote Containers でコンテナとして開いた後で、以下のコマンドを実行してください。
cd example
asciidoctor-pdf example.adoc
hugo-live -D -F
- PDFファイルが、
example/example.pdf
に作成されます。 - VS Code内のブラウザでライブプレビューができます。
example/index.adoc
を編集してみてください。- ブラウザで http://localhost:1313/ を開いても確認できます。
VS Code + Remote Containers でコンテナとして開いた後で、以下のコマンドを実行してください。
cd (生成したいサイトのディレクトリ)
hugo
HTMLのスタイル付けとして、静的サイトジェネレータの Hugo を使用しています。
hugo コマンドの使い方やサイトの構成などは、Hugo の情報を参照してください。
Hugoのバージョンアップでセキュリティが強化され、標準ではAsciiDocの変換ができなくなりました。
設定ファイル(hugo.toml)に以下のような設定を追加してください。
[security.exec]
のallow
に"^asciidoctor$"
を追加[security.exec]
のosEnv
に'^HUGO_'
を追加
https://gohugo.io/about/security-model/#security-policy
[security]
enableInlineShortcodes = false
[security.exec]
allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$', "^asciidoctor$"]
osEnv = ['(?i)^((HTTPS?|NO)_PROXY|PATH(EXT)?|APPDATA|TE?MP|TERM|GO\w+|(XDG_CONFIG_)?HOME|USERPROFILE|SSH_AUTH_SOCK|DISPLAY|LANG|SYSTEMDRIVE)$', '^HUGO_']
[security.funcs]
getenv = ['^HUGO_', '^CI$']
[security.http]
methods = ['(?i)GET|POST']
urls = ['.*']
PlantUMLや数式などの画像を正しく出力するためには、hugo
コマンドを2回実行してください。
Hugoでは公開フォルダ(Public)に、①画像などのファイルのコピーと、②AsciiDocからHTMLへの変換を行います。
PlantUMLなどの画像化は②で行いますが、この時作られた画像は公開フォルダにコピーされないため表示できません。
2回実行することでこれらの画像も公開フォルダにコピーされ、表示が可能となります。
環境変数で以下を変更することができます。
シンタックスハイライトの引数。
rouge-style
にて、テーマを選択できます。
Hugo では、テーマ自体にシンタックスハイライトが組み込まれていることが多いため、 不要な場合は値を空にしてください。
デフォルト値
-a source-highlighter=rouge -a rouge-css=style -a rouge-style=molokai
構文解析だけしたい場合
-a source-highlighter=rouge
Webサイトのベースディレクトリ。
ドメイン直下でない場合はそのディレクトリを指定してください。
上記URLの場合、 someRepos/
部分を設定してください。
デフォルト値
(なし)
HTML 作成時の画像生成ディレクトリ(static配下を指定)
デフォルト値
images/generated
VS Code + Remote Containers でコンテナとして開いた後で、以下のコマンドを実行してください。
asciidoctor-pdf (PDF化対象のAsciiDocファイル)
環境変数で以下を変更することができます。
PDF 作成時の画像パス
デフォルト値
static/images
PDF 作成時の画像生成先パス
デフォルト値
static/images/generated
PDF 作成時のテーマファイル。
default-with-fallback-font
PDF 作成時の rouge (シンタックスハイライト)のスタイル
デフォルト値
molokai
スタイルを github に変更
github
PDF 作成時のフォントファミリー
デフォルト値
M+ 1p Fallback
フォントファミリーをRobotoに変更
Roboto Mono