Other Output Formats

In addition to the default native HTML output, Documenter also provides a built-in LaTeX-based PDF output. Additional output formats are provided through plugin packages. Once the corresponding package is loaded, the output format can be specified using the format option in makedocs.

PDF Output via LaTeX

makedocs can be switched over to use the PDF/LaTeX backend by passing a Documenter.LaTeX object as the format keyword:

using Documenter
makedocs(format = Documenter.LaTeX(), ...)

Documenter will then generate a PDF file of the documentation using LaTeX, which will be placed in the output (build/) directory.

The makedocs argument sitename will be used for the \title field in the tex document, and if the build is for a release tag (i.e. when the "TRAVIS_TAG" environment variable is set) the version number will be appended to the title. The makedocs argument authors should also be specified, it will be used for the \authors field in the tex document.

Known issue

If the makedocs argument pages is not assigned, Documenter will generate tex documents without contents. (#2132)

Compiling using natively installed latex

The following is required to build the documentation:

  • You need pdflatex and latexmk commands to be installed and available to Documenter.
  • You need the minted LaTeX package and its backend source highlighter Pygments installed.
  • You need the DejaVu Sans and DejaVu Sans Mono fonts installed.

Compiling using Tectonic

The documentation can be also built using the Tectonic LaTeX engine. It is required to have a tectonic available in PATH, or to provide a path to the binary using the tectonic keyword:

using Documenter

# Executable `tectonic` is present in `PATH`
makedocs(
    format = Documenter.LaTeX(platform="tectonic"),
    ...)

# The path to `tectonic` is provided by the tectonic_jll package
using tectonic_jll: tectonic
makedocs(
    format = Documenter.LaTeX(platform="tectonic", tectonic=tectonic()),
    ...)

Compiling using docker image

It is also possible to use a prebuilt docker image to compile the .tex file. The image contains all of the required installs described in the section above. The only requirement for using the image is that docker is installed and available for the builder to call. You also need to tell Documenter to use the docker image, instead of natively installed tex which is the default. This is done with the LaTeX specifier:

using Documenter
makedocs(
    format = Documenter.LaTeX(platform = "docker"),
    ...
)

If you build the documentation on Travis you need to add

services:
  - docker

to your .travis.yml file.

Compiling to LaTeX only

There's a possibility to save only the .tex file and skip the PDF compilation. For this purpose use the platform="none" keyword:

using Documenter
makedocs(
    format = Documenter.LaTeX(platform = "none"),
    ...
)

Custom LaTeX style

The PDF/LaTeX backend works by generating a TeX file based on the input Markdown files. For users who need or want more control over the generated PDF, it is possible to customize the setup part of the generated TeX code.

Load custom packages

By default, the generated TeX file loads the documenter.sty style file, which loads several packages (such as fontspec, amsmath, listings, minted, tabulary, graphicx) and otherwise configures the TeX build.

Users can load additional packages and declare additional configuration by adding a custom.sty file to the assets/ source directory. The custom style file will be loaded right after the default style (documenter.sty).

Custom preamble

By default, Documenter uses the preamble.tex preamble, with only the dynamically generated declarations for the \DocMainTitle, \DocVersion, \DocAuthors, and \JuliaVersion variables preceding it.

For more control, it is possible to fully replace the preamble by adding a preamble.tex file into the assets/ source directory, which will then be used instead of the default one. The Documenter tests contain two examples of how a custom preamble can be used:

Markdown & MkDocs

Documenter no longer provides the Markdown/MkDocs output, and this functionality has moved to the DocumenterMarkdown package.