Hugo Theme Vivliocli

hugo-theme-vivliocli is an open-source Hugo theme that turns a Markdown-based documentation site into a site that can also output any section as a typeset PDF using Vivliostyle CLI.

What is hugo-theme-vivliocli?

hugo-theme-vivliocli is a Hugo theme for building document websites that can also output any section containing an _pdf.md file as a typeset PDF with cover, table of contents, bookmarks, chapter numbers, and page numbers. The theme runs on Hugo v0.163.1 or later and uses Vivliostyle CLI v8.6.0 or later as the PDF rendering engine. It is maintained by mochimochiki and released under the Apache License 2.0, with files in assets/js and static/css licensed under CC0-1.0 unless noted.

Key Features

• Typeset PDF output — Sections with an _pdf.md file are rendered as PDFs with cover, TOC, bookmarks, chapter numbers, and page numbers via Vivliostyle CLI.
• Two page styles — Choose a book style with left and right pages or a simple style where all pages are identical.
• Automatic chapter numbering — Chapter numbers are assigned from the Markdown hierarchy and header level; you can specify the output level and the top-level format, for example "Chapter X".
• Complex table drawing — The include shortcode imports a CSV file to draw tables with vertical || and horizontal -> cell merging, supports Markdown syntax inside cells, and lets you set column width and text alignment.
• Mermaid and MathJax support — Embed Mermaid diagrams and MathJax formulas that are pre-rendered with Chromium during PDF generation; this requires network access to CDNs.
• Multi-edition PDF output — The ShowIf and HideIf shortcodes include or exclude blocks or files for specific editions, so you can produce PDF sets with different levels of detail.
• Dockerized build — A Debian-based Docker image bundles Hugo extended, Node.js, Chromium, Ghostscript, poppler, and Noto CJK fonts to build the sample site and generate PDFs without installing anything locally.

Who should use hugo-theme-vivliocli?

Technical writers who need both a web-hosted manual and a print-ready PDF from the same Markdown source will find this theme direct to use. Documentation maintainers can rely on Hugo's content structure plus the _pdf.md convention to keep outputs in sync. Open-source project teams benefit from the included GitHub Actions workflow that builds and uploads PDFs as an artifact, making release documentation reproducible.

What can you do with hugo-theme-vivliocli?

• Technical writing teams: generate typeset PDF user guides from the same Markdown source that powers the website, complete with generated TOC and page numbers.
• Publishers of multi-edition documents: use ShowIf and HideIf to create differently detailed PDF editions, such as a quick-start guide and a full reference manual.
• Developers documenting APIs: combine Mermaid flowcharts and MathJax formulas in pages that export cleanly to PDF for offline distribution.

How does hugo-theme-vivliocli work?

You start by creating a Hugo site and adding the theme as a git submodule with hugo new site MySite followed by the submodule add command. Then you write content in Markdown, placing an _pdf.md file in any section you want to render as a PDF. Finally you run Vivliostyle CLI directly or use the provided docker compose run --rm pdf command to generate the PDFs; a GitHub Actions workflow in the repo also builds and uploads them as the vivliocli-pdf artifact.

Pricing

The theme is free and open source under the Apache License 2.0. No separate pricing tiers exist; you may use, modify, and redistribute it under the license terms.

FAQ

What are the prerequisites for using hugo-theme-vivliocli?

You need Hugo v0.163.1 or later and Vivliostyle CLI v8.6.0 or later. If you prefer not to install these locally, you can use the included Docker image, which bundles Hugo extended, Node.js, Chromium, Ghostscript, poppler, and Noto CJK fonts.

Does PDF generation require network access?

Yes, when your pages use Mermaid or MathJax, Chromium pre-renders them by fetching the libraries from a CDN, so an internet connection is required during the PDF build. The Docker-based build has the same requirement.

Can I output only part of the site as a PDF?

Yes. Any section that contains an _pdf.md file can be output as a PDF. Other sections are not rendered, giving you fine-grained control over what appears in the PDF.

What page styles are available for PDF output?

You can select a book style with distinct left and right pages or a simple style where every page is the same. Chapter numbers are automatically assigned from the Markdown hierarchy, and you can tune their output level and the top-level format.

What license is the theme under?

The theme itself is Apache License 2.0. Files in assets/js and static/css are licensed under CC0-1.0 unless otherwise noted, so you can adapt the JavaScript and CSS freely.