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 can be switched over to use the PDF/LaTeX backend by passing a
Documenter.LaTeX object as the
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 (
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
authors should also be specified, it will be used for the
\authors field in the tex document.
The following is required to build the documentation:
- You need
latexmkcommands 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.
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
using DocumenterLaTeX makedocs( format = LaTeX(platform = "docker"), ... )
If you build the documentation on Travis you need to add
services: - docker
There's a possibility to save only the
.tex file and skip the PDF compilation. For this purpose use the
using DocumenterLaTeX makedocs( format = LaTeX(platform = "none"), ... )
Markdown output requires the
DocumenterMarkdown package to be available and loaded. For Travis setups, add the package to the
docs/Project.toml environment as a dependency. You also need to import the package in
DocumenterMarkdown is loaded, you can specify
format = Markdown() in
makedocs. Documenter will then output a set of Markdown files to the
build directory that can then further be processed with MkDocs into HTML pages.
MkDocs, of course, is not the only option you have – any markdown to HTML converter should work fine with some amount of setting up.
Markdown output used to be the default option (i.e. when leaving the
format option unspecified). The default now is the HTML output.
A MkDocs build is controlled by the
mkdocs.yml configuration file. Add the file with the following content to the
If you have run Documenter and it has generated a
build/ directory, you can now try running
mkdocs build – this should now generate the
site/ directory. You should also add the
docs/site/ directory into your
.gitignore file, which should now look like:
This is only a basic skeleton. Read through the MkDocs documentation if you would like to know more about the available settings.
deploydocs( repo = "github.com/USER_NAME/PACKAGE_NAME.jl.git", deps = Deps.pip("mkdocs", "pygments", "python-markdown-math"), make = () -> run(`mkdocs build`) target = "site" )
depsserves to provide the required Python dependencies to build the documentation
makespecifies the function that calls
mkdocsto perform the second build step
target, which specified which files get copied to
gh-pages, needs to point to the
In the example above we include the dependencies mkdocs and
python-markdown-math. The former makes sure that MkDocs is installed to deploy the documentation, and the latter provides the
mdx_math markdown extension to exploit MathJax rendering of latex equations in markdown. Other dependencies should be included here.
To get MkDocs to display $\LaTeX$ equations correctly we need to update several of this configuration files described in the Package Guide.
docs/make.jl should add the
python-markdown-math dependency to allow for equations to be rendered correctly.
# ... deploydocs( deps = Deps.pip("pygments", "mkdocs", "python-markdown-math"), # ... )
This package should also be installed locally so that you can preview the generated documentation prior to pushing new commits to a repository.
$ pip install python-markdown-math
docs/mkdocs.yml file must add the
python-markdown-math extension, called
Following this guide and adding the necessary changes to the configuration files should enable properly rendered mathematical equations within your documentation both locally and when built and deployed using the Travis built service.