Writers

Writes a Documenter.Document object to .user.build directory in the formats specified in the .user.format vector.

Adding additional formats requires adding new Selector definitions as follows:

abstract type CustomFormat <: FormatSelector end

Selectors.order(::Type{CustomFormat}) = 4.0 # or a higher number.
Selectors.matcher(::Type{CustomFormat}, fmt, _) = fmt === :custom
Selectors.runner(::Type{CustomFormat}, _, doc) = CustomWriter.render(doc)

# Definition of `CustomWriter` module below...

A module for rendering Document objects to HTML.

Keywords

HTMLWriter uses the following additional keyword arguments that can be passed to Documenter.makedocs: authors, pages, sitename, version. The behavior of HTMLWriter can be further customized by setting the format keyword of Documenter.makedocs to a HTML, which accepts the following keyword arguments: analytics, assets, canonical, disable_git, edit_link, prettyurls, collapselevel, sidebar_sitename, highlights, mathengine and footer.

sitename is the site's title displayed in the title bar and at the top of the *navigation menu. It is also written into the inventory (see below). This argument is mandatory for HTMLWriter.

pages defines the hierarchy of the navigation menu.

Experimental keywords

version specifies the version string of the current version which will be the selected option in the version selector. If this is left empty (default) the version selector will be hidden. The special value git-commit sets the value in the output to git:{commit}, where {commit} is the first few characters of the current commit hash.

HTML Plugin options

The HTML object provides additional customization options for the HTMLWriter. For more information, see the HTML documentation.

Page outline

The HTMLWriter makes use of the page outline that is determined by the headings. It is assumed that if the very first block of a page is a level 1 heading, then it is intended as the page title. This has two consequences:

1. It is then used to automatically determine the page title in the navigation menu and in the <title> tag, unless specified in the .pages option.
2. If the first heading is interpreted as being the page title, it is not displayed in the navigation sidebar.

Inventory

The HTMLWriter automatically generates an objects.inv "inventory" file in the output build folder. This file contains a list of all pages, headers and docstrings in the documentation, and a relative URL that can be used to link to those items from an external source.

Other projects that build their documentation with Documenter can use the DocumenterInterLinks plugin to link to any other project with an inventory file, see External Cross-References.

The format of the objects.inv file is borrowed from the Sphinx project. It consists of a plain text header that includes the project name, taken from the sitename argument to Documenter.makedocs, and a project version taken from the inventory_version argument of the HTML options, or automatically determined by deploydocs for tagged releases. The bulk of the file is a list of plain text records, compressed with gzip. See Inventory Generation for details on these records.

The root directory of the HTML assets.

The directory where all the Sass/SCSS files needed for theme building are.

Directory for the compiled CSS files of the themes.

Data attribute for the script inserting a warning for outdated docs.

List of Documenter native themes.

HTML(kwargs...)

Sets the behavior of HTMLWriter.

Keyword arguments

prettyurls (default true) – allows toggling the pretty URLs feature.

By default (i.e., when prettyurls is set to true), Documenter creates a directory structure that hides the .html suffixes from the URLs (e.g., by default src/foo.md becomes src/foo/index.html, but can be accessed via src/foo/ in the browser). This structure is preferred when publishing the generated HTML files as a website (e.g., on GitHub Pages), which is Documenter's primary use case. However, when building locally, viewing the resulting pages requires a running webserver. It is recommended to use the LiveServer package for this.

If prettyurls = false, then Documenter generates src/foo.html instead.

disable_git can be used to disable calls to git when the document is not in a Git-controlled repository. Without setting this to true, Documenter will throw an error and exit if any of the Git commands fail. The calls to Git are mainly used to gather information about the current commit hash and file paths, necessary for constructing the links to the remote repository.

edit_link can be used to specify which branch, tag or commit (when passed a String) in the remote repository the edit buttons point to. If a special Symbol value :commit is passed, the current commit will be used instead. If set to nothing, the link edit link will be hidden altogether. By default, Documenter tries to determine it automatically by looking at the origin remote, and falls back to "master" if that fails.

repolink can be used to override the URL of the Git repository link in the top navbar (if passed a String). By default, Documenter attempts to determine the link from the Git remote of the repository (e.g. specified via the remotes argument of makedocs). Passing a nothing disables the repository link.

canonical specifies the canonical URL for your documentation. We recommend you set this to the base url of your stable documentation, e.g. https://documenter.juliadocs.org/stable. This allows search engines to know which version to send their users to. See wikipedia for more information. Default is nothing, in which case no canonical link is set.

assets can be used to include additional assets (JS, CSS, ICO etc. files). See below for more information.

analytics can be used specify the Google Analytics tracking ID.

collapselevel controls the navigation level visible in the sidebar. Defaults to 2. To show fewer levels by default, set collapselevel = 1.

sidebar_sitename determines whether the site name is shown in the sidebar or not. Setting it to false can be useful when the logo already contains the name of the package. Defaults to true.

highlights can be used to add highlighting for additional languages. By default, Documenter already highlights all the "Common" highlight.js languages and Julia (julia, julia-repl). Additional languages must be specified by their filenames as they appear on CDNJS for the highlight.js version Documenter is using. E.g. to include highlighting for YAML and LLVM IR, you would set highlights = ["llvm", "yaml"]. Note that no verification is done whether the provided language names are sane.

mathengine specifies which LaTeX rendering engine will be used to render the math blocks. The options are either KaTeX (default), MathJax v2, or MathJax v3, enabled by passing an instance of KaTeX, MathJax2, or MathJax3 objects, respectively. The rendering engine can further be customized by passing options to the KaTeX or MathJax2/MathJax3 constructors.

description is the site-wide description that displays in page previews and search engines. Defaults to "Documentation for $sitename", where sitename is defined as an argument to makedocs.

footer can be a valid single-line markdown String or nothing and is displayed below the page navigation. Defaults to "Powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) and the [Julia Programming Language](https://julialang.org/).".

ansicolor can be used to globally disable colored output from @repl and @example blocks by setting it to false (default: true).

lang specifies the lang attribute of the top-level <html> element, declaring the language of the generated pages. The default value is "en".

warn_outdated inserts a warning if the current page is not the newest version of the documentation.

example_size_threshold specifies the size threshold above which the @example and other block outputs get written to files, rather than being included in the HTML page. This mechanism is present to reduce the size of the generated HTML files that contain a lot of figures etc. Setting it to nothing will disable writing to files, and setting to 0 means that all examples will be written to files. Defaults to 8 KiB.

size_threshold sets the maximum allowed HTML file size (in bytes) that Documenter is allowed to generate for a page. If the generated HTML file is larged than this, Documenter will throw an error and the build will fail. If set to nothing, the file sizes are not checked. Defaults to 200 KiB (but increases of this default value will be considered to be non-breaking).

size_threshold_warn: like size_threshold, but going over this limit will only cause Documenter to print a warning, instead of throwing an error. Defaults to 100 KiB, and must be less than or equal to size_threshold.

size_threshold_ignore can be passed a list of pages for which the size thresholds are completely ignored (silently). The arguments should be the same file paths as for the pages argument of makedocs. Using this argument to ignore a few specific pages is preferred over setting a high general limit, or disabling the size checking altogether.

Experimental options

prerender a boolean (true or false (default)) for enabling prerendering/build time application of syntax highlighting of code blocks. Requires a node (NodeJS) executable to be available in PATH or to be passed as the node keyword.

node path to a node (NodeJS) executable used for prerendering.

highlightjs file path to custom highglight.js library to be used with prerendering.

inventory_version a version string to write to the header of the objects.inv inventory file. This should be a valid version number without a v prefix. Defaults to the version defined in the Project.toml file in the parent folder of the documentation root. Setting this to an empty string leaves the version in the inventory unspecified until deploydocs runs and automatically sets the version for any tagged release.

Default and custom assets

Documenter copies all files under the source directory (e.g. /docs/src/) over to the compiled site. It also copies a set of default assets from /assets/html/ to the site's assets/ directory, unless the user already had a file with the same name, in which case the user's files overrides the Documenter's file. This could, in principle, be used for customizing the site's style and scripting.

The HTML output also links certain custom assets to the generated HTML documents, specifically a logo, a preview image, and additional javascript files. The asset files that should be linked must be placed in assets/, under the source directory (e.g /docs/src/assets) and must be on the top level (i.e. files in the subdirectories of assets/ are not linked).

For the logo, Documenter checks for the existence of assets/logo.{svg,png,webp,gif,jpg,jpeg}, in this order. The first one it finds gets displayed at the top of the navigation sidebar. It will also check for assets/logo-dark.{svg,png,webp,gif,jpg,jpeg} and use that for dark themes.

Similarly, for the preview image, Documenter checks for the existence of assets/preview.{png,webp,gif,jpg,jpeg} in order. Assuming that canonical has been set, the canonical URL for the image gets constructed, , and a set of HTML <meta> tags are generated for the image, ensuring that the image shows up in link previews. The preview image will not be shown if canonical is not set.

Additional JS, ICO, and CSS assets can be included in the generated pages by passing them as a list with the assets keyword. Each asset will be included in the <head> of every page in the order in which they are given. The type of the asset (i.e. whether it is going to be included with a <script> or a <link> tag) is determined by the file's extension – either .js, .ico^[1], or .css (unless overridden with asset).

Simple strings are assumed to be local assets and that each correspond to a file relative to the documentation source directory (conventionally src/). Non-local assets, identified by their absolute URLs, can be included with the asset function.

HTMLWriter-specific globals that are passed to domify and other recursive functions.

KaTeX(config::Dict = <default>, override = false)

An instance of the KaTeX type can be passed to HTML via the mathengine keyword to specify that the KaTeX rendering engine should be used in the HTML output to render mathematical expressions.

A dictionary can be passed via the config argument to configure KaTeX. It becomes the options argument of renderMathInElement. By default, Documenter only sets a custom delimiters option.

By default, the user-provided dictionary gets merged with the default dictionary (i.e. the resulting configuration dictionary will contain the values from both dictionaries, but e.g. setting your own delimiters value will override the default). This can be overridden by setting override to true, in which case the default values are ignored and only the user-provided dictionary is used.

MathJax2(config::Dict = <default>, override = false)

An instance of the MathJax2 type can be passed to HTML via the mathengine keyword to specify that the MathJax v2 rendering engine should be used in the HTML output to render mathematical expressions.

A dictionary can be passed via the config argument to configure MathJax. It gets passed to the MathJax.Hub.Config function. By default, Documenter sets custom configurations for tex2jax, config, jax, extensions and Tex.

By default, the user-provided dictionary gets merged with the default dictionary (i.e. the resulting configuration dictionary will contain the values from both dictionaries, but e.g. setting your own tex2jax value will override the default). This can be overridden by setting override to true, in which case the default values are ignored and only the user-provided dictionary is used.

The URL of the MathJax JS file can be overridden using the url keyword argument (e.g. to use a particular minor version).

MathJax3(config::Dict = <default>, override = false)

An instance of the MathJax3 type can be passed to HTML via the mathengine keyword to specify that the MathJax v3 rendering engine should be used in the HTML output to render mathematical expressions.

A dictionary can be passed via the config argument to configure MathJax. It gets passed to Window.MathJax function. By default, Documenter specifies in the key tex that $...$ and \(...\) denote inline math, that AMS style tags should be used and the base, ams and autoload packages should be imported. The key options, by default, specifies which HTML classes to ignore and which to process using MathJax.

By default, the user-provided dictionary gets merged with the default dictionary (i.e. the resulting configuration dictionary will contain the values from both dictionaries, but e.g. setting your own tex value will override the default). This can be overridden by setting override to true, in which case the default values are ignored and only the user-provided dictionary is used.

The URL of the MathJax JS file can be overridden using the url keyword argument (e.g. to use a particular minor version).

deprecated – Use MathJax2 instead

If canonical for HTML is set, returns the canonical URL of a path or Documenter.NavNode, otherwise returns nothing.

Returns an ordered list of tuples, (toplevel, anchor, text), corresponding to level 1 and 2 headings on the page. Note that if the first header on the page is a level 1 header then it is not included – it is assumed to be the page title and so does not need to be included in the navigation menu twice.

Copies an asset from Documenters assets/html/ directory to doc.user.build. Returns the path of the copied asset relative to .build.

Returns the first limit characters of the hex SHA1 of the data bytes.

Calls f(logo, title, url) if it is possible to create an edit link for the navnode.

Calculates and converts bytes to appropriate format.

Returns the full path corresponding to a path of a .md page file. The the input and output paths are assumed to be relative to src/.

Returns the full path of a Documenter.NavNode relative to src/.

Returns a page (as a Documenter.Page object) using the HTMLContext.

Get the relative hyperlink between two Documenter.NavNodes. Assumes that both Documenter.NavNodes have an associated Documenter.Page (i.e. .page is not nothing).

navitem returns the lists and list items of the navigation menu. It gets called recursively to construct the whole tree.

It always returns a DOM.Node. If there's nothing to display (e.g. the node is set to be invisible), it returns an empty text node (DOM.Node("")).

Tries to guess the page title by looking at the <h1> headers and returns the header contents of the first <h1> on a page (or nothing if the algorithm was unable to find any <h1> headers).

If prettyurls for HTML is enabled, returns a "pretty" version of the path which can then be used in links in the resulting HTML file.

Calculates a relative HTML link from one path to another.

Renders the main <html> tag.

Constructs and writes the page referred to by the navnode to .build.

Renders the modal settings dialog.

Generates a unique file for the output of an at-example block if it goes over the configured size threshold, and returns the filename (that should be in the same directory are the corresponding HTML file). If the data is under the threshold, no file is created, and the function returns nothing.

Writes the HTML DOM into the HTML file that corresponds to navnode. Prints a warning/error if the page goes over the size_threshold or size_threshold_warn limits, and in the former case also returns false, to report back to the caller that the size threshold check failed.

Generate the objects.inv inventory file.

Write the file objects.inv to the root of the HTML build folder, containing an inventory of all linkable targets in the documentation (pages, headings, and docstrings).

The objects.inv file is compatible with Sphinx See DocInventories for a description. The file can be used by Intersphinx and the DocumenterInterLinks plugin to link into the documentation from other projects.

Provides a namespace for remote dependencies.

Add the highlight.js dependencies and snippet to a RequireJS declaration.

A module for rendering Document objects to LaTeX and PDF.

Keywords

LaTeXWriter uses the following additional keyword arguments that can be passed to makedocs: authors, sitename.

sitename is the site's title displayed in the title bar and at the top of the navigation menu. It goes into the \title LaTeX command.

authors can be used to specify the authors of. It goes into the \author LaTeX command.

Documenter.LaTeX(; kwargs...)

Output format specifier that results in LaTeX/PDF output. Used together with makedocs, e.g.

makedocs(
    format = Documenter.LaTeX()
)

The makedocs argument sitename will be used for the \title field in the tex document. The authors argument should also be specified and will be used for the \authors field in the tex document. Finally, a version number can be specified with the version option to LaTeX, which will be printed in the document and also appended to the output PDF file name.

Keyword arguments

platform sets the platform where the tex-file is compiled, either "native" (default), "tectonic", "docker", or "none" which doesn't compile the tex. The option tectonic requires a tectonic executable to be available in PATH or to be passed as the tectonic keyword.

version specifies the version number that gets printed on the title page of the manual. It defaults to the value in the TRAVIS_TAG environment variable (although this behaviour is considered to be deprecated), or to an empty string if TRAVIS_TAG is unset.

tectonic path to a tectonic executable used for compilation.

See Other Output Formats for more information.

abstract type Plugin end

Any plugin that needs to either solicit user input or store information in a Document should create a subtype of Plugin, i.e., T <: DocumenterPlugin.

Initialized objects of type T can be elements of the list of plugins passed as a keyword argument to makedocs.

A plugin may retrieve the existing object holding its state via the Documenter.getplugin function. Alternatively, getplugin can also instantiate T() on demand, if there is no existing object. This requires that T implements an empty constructor T().