第1章Getting Started

1.1対象環境

本解説は Windows を対象環境としています。

1.2インストール

Hugoのインストール

Hugo を 公式ページのインストール手順 に従いインストールします。インストールが完了したら、以下のコマンドでHugoのバージョンが表示されることを確認します。

hugo version
:: Hugo Static Site Generator vx.xx.x ...

Node.jsとVivliostyleのインストール

Node.js のLTS版をインストールします。インストールが完了したら、以下のコマンドでNode.jsおよびnpmのバージョンが表示されることを確認します。

node -v
:: vX.X.X
:: note: vivliostyle-cli is not working in Node v14.0.0

npm -v
:: X.X.X

次にnpmで vivliostyle-cli をインストールします。インストールが完了したら、Vivliostyleのバージョンが表示されることを確認します。

npm install -g @vivliostyle/cli
vivliostyle -v
:: cli: X.X.X
:: core: X.X.X

サイト作成とテーマのインストール

Hugoで新しいサイトを作成します。ここではmyPDFという名称とします。

hugo new site myPDF
cd myPDF

releases から最新のSource code (zip)をダウンロード・解凍し、/themes/hugo-theme-vivliocliに配置します。

Note

gitを利用する場合、submoduleとして導入することもできます。

git init
git submodule add https://github.com/mochimochiki/hugo-theme-vivliocli themes/hugo-theme-vivliocli

exampleSiteからファイルをコピーする

テーマの中にテンプレートとして利用できるexampleSiteがあります。exampleSiteから必要なファイルをコピーします。また、デフォルトのconfig.tomlは削除しておきます。

xcopy /s themes\hugo-theme-vivliocli\exampleSite\config config\
xcopy /s themes\hugo-theme-vivliocli\exampleSite\CI CI\
del config.toml

1.3最初のサイトの作成

config.tomlの編集

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

themesdir = "../.."

また、baseURL, title を編集します。

baseURL = ""
title = "My PDF Site"

表紙の作成

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

mkdir content\ja\firstpdf
mkdir content\en\firstpdf

次にja/firstpdf/_pdf.mdファイルを作成して以下のように編集し、文字コードUTF-8で保存します。このファイルはPDFの表紙/前書/目次となります。_pdf.mdを配置したディレクトリ下がPDF出力の単位となります。

---
pdfname: 'firstpdf'
doctitle: 'My first pdf'
subtitle: 'subtitle'
header: '2023/1/1'
author: 'auther'
pagesize: 'A4'
book: true
cover: true
toc: true
sectionNumberLevel: 2
colophon: false
outputs:
- vivlio_cover
- vivlio_config
---
Note

詳細は _pdf.mdの設定 を参照してください。

記事の作成

次に記事を作成します。/content/ja/firstpdfに_index.mdを作成して以下のように編集します。

---
title: "firstpdf"
weight: 10
---

`_index.md`はサイト上のセクションページになります。PDFには含まれません。

また/content/ja/firstpdf下にfirst.md, second.mdを作成して以下のように編集して保存します。

---
title: "最初の記事"
weight: 10
---

## 最初の記事

こんにちは。これは最初の記事です。

---
title: "次の記事"
weight: 20
---

## 次の記事

こんにちは。これは次の記事です。

以下のコマンドでHugoのプレビューを表示してメニューのLanguages からJapaneseを選択し、作成した記事が表示されることを確認します。記事を編集して保存すると、LiveReloadがかかり、プレビューも更新されます。

hugo server --config config\default.toml

ビルド

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

cd CI\windows
build_pdf.bat

エラーが出力された場合、PDFを開いたままにしていないか確認してください。開いているとPDFの上書きに失敗します。

/public_default/ja/firstPDF.pdfが成果物です。確認してみましょう。

章節番号をカスタマイズする

1.1などの章節番号の出力レベルは_pdf.mdでカスタマイズすることができます。_pdf.mdを開き、以下の箇所を変更してみましょう。

sectionNumberLevel: 2 # -> 1に変更

また、トップレベルの出力形式やデリミタの設定は /config/default.toml で設定できます。

  [languages.ja.params]
    sectionDelimiter = "."
    sectionTopFormat = "第%s章" # -> "Chapter %s" に変更

その他のconfigパラメータについては config.tomlの設定 および HUGO公式ドキュメント などを参照してください。

/public_default/ja/firstpdf.pdf で以下のことを確認します。

1.4NextStep