Public Documentation

Documentation for Documenter.jl's public interface.

See the Internals section of the manual for internal package docs covering all submodules.



Public Interface

    root    = "<current-directory>",
    source  = "src",
    build   = "build",
    clean   = true,
    doctest = true,
    modules = Module[],
    repo    = "",
    highlightsig = true,
    sitename = "",
    expandfirst = [],
    draft = false,

Combines markdown files and inline docstrings into an interlinked document. In most cases makedocs should be run from a make.jl file:

using Documenter
    # keywords...

which is then run from the command line with:

$ julia make.jl

The folder structure that makedocs expects looks like:



root is the directory from which makedocs should run. When run from a make.jl file this keyword does not need to be set. It is, for the most part, needed when repeatedly running makedocs from the Julia REPL like so:

julia> makedocs(root = joinpath(dirname(pathof(MyModule)), "..", "docs"))

source is the directory, relative to root, where the markdown source files are read from. By convention this folder is called src. Note that any non-markdown files stored in source are copied over to the build directory when makedocs is run.

build is the directory, relative to root, into which generated files and folders are written when makedocs is run. The name of the build directory is, by convention, called build, though, like with source, users are free to change this to anything else to better suit their project needs.

clean tells makedocs whether to remove all the content from the build folder prior to generating new content from source. By default this is set to true.

doctest instructs makedocs on whether to try to test Julia code blocks that are encountered in the generated document. By default this keyword is set to true. Doctesting should only ever be disabled when initially setting up a newly developed package where the developer is just trying to get their package and documentation structure correct. After that, it's encouraged to always make sure that documentation examples are runnable and produce the expected results. See the Doctests manual section for details about running doctests.

Setting doctest to :only allows for doctesting without a full build. In this mode, most build stages are skipped and the warnonly keyword is ignored (a doctesting error will always make makedocs throw an error in this mode).

modules specifies a vector of modules that should be documented in source. If any inline docstrings from those modules are seen to be missing from the generated content then a warning will be printed during execution of makedocs. By default no modules are passed to modules and so no warnings will appear. This setting can be used as an indicator of the "coverage" of the generated documentation. For example Documenter's make.jl file contains:

    modules = [Documenter],
    # ...

and so any docstring from the module Documenter that is not spliced into the generated documentation in build will raise a warning.

repo specifies the remote hosted Git repository (e.g. on related to the documentation build. It should be passed an object that subtypes and implements the Remotes.Remote interface (e.g. Remotes.GitHub). A template string can also be passed (interpreted according to the rules described in Remotes.URL), but the use of the template strings is discouraged, in favor of concrete Remotes.Remote objects.

remotes can be used to declare a list additional path::AbstractString => remote pairs that are used to determine the remote repository URLs for local filesystem files, such as the edit links for manual Markdown pages, or docstring source links. path should be an absolute local filesystem path to a directory, and will be interpreted as the root of the remote repository specified with remote. remote would normally be Remote object, but can also be a (remote::Remote, commit::AbstractString) tuple, where the second argument specifies the commit within the repository. This is necessary when path is not pointing to a proper Git repository, and so determining the commit automatically is not possible.

If repo is not passed, makedocs will try to determine it automatically, either by inspecting the locally checked out Git repository, or via the remotes keyword. See the manual section on Remote repository links for more information on how the remote repository links are handled.

If remotes is set to nothing, all remote repository links (repository links, source links, edit links, issue links etc.) will be completely disabled. This can be useful when publicly deploying documentation for private packages.

highlightsig enables or disables automatic syntax highlighting of leading, unlabeled code blocks in docstrings (as Julia code). For example, if your docstring begins with an indented code block containing the function signature, then that block would be highlighted as if it were a labeled Julia code block. No other code blocks are affected. This feature is enabled by default.

sitename is displayed in the title bar and/or the navigation menu when applicable.

pages can be use to specify a hierarchical page structure, and the order in which the pages appear in the navigation of the rendered output. If omitted, Documenter will automatically generate a flat list of pages based on the files present in the source directory.

pages = [
    "Overview" => "",
    "Tutorial" => [
        "Advanced" => "tutorial/",

The pages keyword must be a list where each element must be one of the following:

  1. A string containing the full path of a Markdown file within the source directory (i.e. relative to the docs/src/ root in standard deployments).
  2. A "Page title" => "path/to/" pair, where Page title overrides the page title in the navigation menu (but not on the page itself).
  3. A "Subsection title" => [...] pair, indicating a subsection of pages with the given title in the navigation menu. The list of pages for the subsection follow the same rules as the top-level pages keyword.

See also hide, which can be used to hide certain pages in the navigation menu.

Note that, by default, regardless of what is specified in pages, Documenter will run and render all Markdown files it finds, even if they are not present in pages. The pagesonly keyword can be used to change this behaviour.

pagesonly can be set to true (default: false) to make Documenter process only the pages listed in with the pages keyword. In that case, the Markdown files not present in pages are ignored, i.e. code blocks do not run, docstrings do not get included, and the pages are not rendered in the output in any way.

expandfirst allows some of the pages to be expanded (i.e. at-blocks evaluated etc.) before the others. Documenter normally evaluates the files in the alphabetic order of their file paths relative to src, but expandfirst allows some pages to be prioritized.

For example, if you have and, would normally be evaluated before But with expandfirst = [""], you can force to be evaluated first.

Evaluation order among the expandfirst pages is according to the order they appear in the argument.

draft can be set to true to build a draft version of the document. In draft mode some potentially time-consuming steps are skipped (e.g. running @example blocks), which is useful when iterating on the documentation. This setting can also be configured per-page by setting Draft = true in an @meta block.

checkdocs instructs makedocs to check whether all names within the modules defined in the modules keyword that have a docstring attached have the docstring also listed in the manual (e.g. there's a @docs block with that docstring). Possible values are :all (check all names; the default), :exports (check only exported names) and :none (no checks are performed).

By default, if the document check detect any errors, it will fail the documentation build. This behavior can be relaxed with the warnonly keyword.

linkcheck – if set to true makedocs uses curl to check the status codes of external-pointing links, to make sure that they are up-to-date. The links and their status codes are printed to the standard output. When enabled, any detected errors will fail the build, but this can be overridden by passing :linkcheck to warnonly. Default: false.

linkcheck_ignore allows certain URLs to be ignored in linkcheck. The values should be a list of strings (which get matched exactly) or Regex objects. By default nothing is ignored.

linkcheck_timeout configures how long curl waits (in seconds) for a link request to return a response before giving up. The default is 10 seconds.

warnonly can be used to control whether the makedocs build fails with an error, or simply prints a warning if it detects any issues with the document. Additionally, a Symbol or a Vector of Symbols can be passed to make Documenter warn for only those specified error classes (see also: Documenter.except). If set to true, the build should never fail due to document checks. The keyword defaults to false.

Note that setting warnonly = true in general is not recommended, since it will make it very easy to miss Documentation build issues, and will lead to the deployment of broken manuals. The only case where you may want to consider passing true is when you are automatically deploying the documentation for a package release. In that case, warnonly should be set dynamically by checking the relevant environment variables set by the CI system.

workdir determines the working directory where @example and @repl code blocks are executed. It can be either a path or the special value :build (default).

If the workdir is set to a path, the working directory is reset to that path for each code block being evaluated. Relative paths are taken to be relative to root, but using absolute paths is recommended (e.g. workdir = joinpath(@__DIR__, "..") for executing in the package root for the usual docs/make.jl setup).

With the default :build option, the working directory is set to a subdirectory of build, determined from the source file path. E.g. for src/ it is set to build/, for src/foo/ it is set to build/foo etc.

Note that workdir does not affect doctests.

plugins is a list of Documenter.Plugin objects. Use as directed by the documentation of a third-party plugin. For any subtype T <: Plugin, the plugins list may contain at most a single object of type T.

Output formats

format allows the output format to be specified. The default format is Documenter.HTML which creates a set of HTML files, but Documenter also provides PDF output via the Documenter.LaTeX writer.

Other formats can be enabled by using other addon-packages. For example, the DocumenterMarkdown package provides the original Markdown -> Markdown output. See the Other Output Formats for more information.

See Also

A guide detailing how to document a package using Documenter's makedocs is provided in the setup guide in the manual.


Returns the list of all valid error classes that can be passed as the warnonly argument of makedocs, except for the ones specified in the errors argument. Each error class must be a Symbol and passed as a separate argument.

This can be used to enable strict error checking for only the listed error classes, while having other error types simply print a warning. E.g. to make Documenter fail the build only for footnote and linkcheck errors, one can set warnonly as

    warnonly = Documenter.except(:linkcheck, :footnote),

The possible Symbol values that can be passed to the function are: :autodocs_block, :cross_references, :docs_block, :doctest, :eval_block, :example_block, :footnote, :linkcheck_remotes, :linkcheck, :meta_block, :missing_docs, :parse_error, and :setup_block.


Allows a page to be hidden in the navigation menu. It will only show up if it happens to be the current page. The hidden page will still be present in the linear page list that can be accessed via the previous and next page links. The title of the hidden page can be overridden using the => operator as usual.


    pages = [
        hide("Title" => "")
hide(root, children)

Allows a subsection of pages to be hidden from the navigation menu. root will be linked to in the navigation menu, with the title determined as usual. children should be a list of pages (note that it can not be hierarchical).


    pages = [
        hide("Hidden section" => "", [
            "Hidden 2" => ""
        hide("", [...])

Can be used to pass non-local web assets to HTML, where uri should be an absolute HTTP or HTTPS URL.

It accepts the following keyword arguments:

class can be used to override the asset class, which determines how exactly the asset gets included in the HTML page. This is necessary if the class can not be determined automatically (default).

Should be one of: :js, :css or :ico. They become a <script>, <link rel="stylesheet" type="text/css"> and <link rel="icon" type="image/x-icon"> elements in <head>, respectively.

islocal can be used to declare the asset to be local. The uri should then be a path relative to the documentation source directory (conventionally src/). This can be useful when it is necessary to override the asset class of a local asset.


Documenter.HTML(assets = [
    # Standard local asset
    # Standard remote asset (extension used to determine that class = :js)
    # Setting asset class manually, since it can't be determined manually
    asset("", class = :css),
    # Same as above, but for a local asset
    asset("asset/foo.script", class=:js, islocal=true),
    root = "<current-directory>",
    target = "build",
    dirname = "",
    repo = "<required>",
    branch = "gh-pages",
    deps = nothing | <Function>,
    make = nothing | <Function>,
    cname = nothing | <String>,
    devbranch = nothing,
    devurl = "dev",
    versions = ["stable" => "v^", "v#.#", devurl => devurl],
    forcepush = false,
    deploy_config = auto_detect_deploy_system(),
    push_preview = false,
    repo_previews = repo,
    branch_previews = branch,
    tag_prefix = "",

Copies the files generated by makedocs in target to the appropriate (sub-)folder in dirname on the deployment branch, commits them, and pushes to repo.

This function should be called from within a package's docs/make.jl file after the call to makedocs, like so

using Documenter, PACKAGE_NAME
    # options...
    repo = ""

When building the docs for a tag (i.e. a release) the documentation is deployed to a directory with the tag name (i.e. vX.Y.Z) and to the stable directory. Otherwise the docs are deployed to the directory determined by the devurl argument.

The deployment procedure consists of the following steps:

  • Check out the branch of repo to a temporary location.
  • Remove the existing deployment (sub-)directory with git rm -r.
  • Copy the target (build) folder to the deployment directory.
  • Generate index.html, and versions.js in the branch root and siteinfo.js in the deployment directory.
  • Add all files on the deployment branch (git add -A .), commit them, and push the repo. Note that any .gitignore files in the target directory affect which files will be committed to branch.

The index.html will be created at the branch root if and only if one of the following two conditions hold:

  1. No such file already exists.

  2. The file exists and starts with the HTML comment

    <!--This file is automatically generated by Documenter.jl-->

Required keyword arguments

repo is the remote repository where generated HTML content should be pushed to. Do not specify any protocol - "https://" or "git@" should not be present. This keyword must be set and will throw an error when left undefined. For example this package uses the following repo value:

repo = ""

Optional keyword arguments

deploy_config determines configuration for the deployment. If this is not specified Documenter will try to autodetect from the currently running environment. See the manual section about Deployment systems.

root has the same purpose as the root keyword for makedocs.

target is the directory, relative to root, where generated content that should be deployed to gh-pages is written to. It should generally be the same as makedocs's build and defaults to "build".

branch is the branch where the generated documentation is pushed. If the branch does not exist, a new orphaned branch is created automatically. It defaults to "gh-pages".

dirname is a subdirectory of branch that the docs should be added to. By default, it is "", which will add the docs to the root directory.

cname is the CNAME where the documentation will be hosted, which is equivalent to the GitHub Pages "Custom domain" setting in the repository settings. If set, it will be used to generate the CNAME file, which has a higher priority than the GitHub Pages settings.

devbranch is the branch that "tracks" the in-development version of the generated documentation. By default Documenter tries to figure this out using git. Can be set explicitly as a string (typically "master" or "main").

devurl the folder that in-development version of the docs will be deployed. Defaults to "dev".

forcepush a boolean that specifies the behavior of the git-deployment. The default (forcepush = false) is to push a new commit, but when forcepush = true the changes will be combined with the previous commit and force pushed, erasing the Git history on the deployment branch.

versions determines content and order of the resulting version selector in the generated html. The following entries are valid in the versions vector:

  • "v#": includes links to the latest documentation for each major release cycle (i.e. v2.0, v1.1).
  • "v#.#": includes links to the latest documentation for each minor release cycle (i.e. v2.0, v1.1, v1.0, v0.1).
  • "v#.#.#": includes links to all released versions.
  • "v^": includes a link to the docs for the maximum version (i.e. a link vX.Y pointing to vX.Y.Z for highest X, Y, Z, respectively).
  • A pair, e.g. "first" => "second", which will put "first" in the selector, and generate a url from which "second" can be accessed. The second argument can be "v^", to point to the maximum version docs (as in e.g. "stable" => "v^").

If versions = nothing documentation will be deployed directly to the "root", i.e. not to a versioned subfolder. See the manual section on Deploying without the versioning scheme for more details.

push_preview a boolean that specifies if preview documentation should be deployed from pull requests or not. If your published documentation is hosted at ", by default the preview will be hosted at "". This feature works for pull requests with head branch in the same repository, i.e. not from forks.

branch_previews is the branch to which pull request previews are deployed. It defaults to the value of branch.

repo_previews is the remote repository to which pull request previews are deployed. It defaults to the value of repo.


Pull requests made from forks will not have previews. Hosting previews requires access to the deploy key. Therefore, previews are available only for pull requests that were submitted directly from the main repository. On GitHub Actions, GITHUB_TOKEN must be present for previews to work, even if DOCUMENTER_KEY ise being used to deploy.


Previews generated are NOT automatically cleaned up. This can be done manually or automated. A GitHub Actions workflow for automating the same can be found here.

deps can be set to a function or a callable object and gets called during deployment, and is usually used to install additional dependencies. By default, nothing gets executed.

make can be set to a function or a callable object and gets called during deployment, and is usually used to specify additional build steps. By default, nothing gets executed.

tag_prefix can be set to allow prefixed version numbers to determine the version number of a release. If tag_prefix = "" (the default), only version tags will trigger deployment; with a non-empty tag_prefix, only version tags with that prefix will trigger deployment. See manual sections on Documentation Versions and Deploying from a monorepo for more details.

Releases vs development branches

deploydocs will automatically figure out whether it is deploying the documentation for a tagged release or just a development branch (usually, based on the environment variables set by the CI system).

With versioned tags, deploydocs discards the build metadata (i.e. + and everything that follows it) from the version number when determining the name of the directory into which the documentation gets deployed, as well as the tag_prefix (if present). Pre-release identifiers are preserved.

See Also

The Hosting Documentation section of the manual provides a step-by-step guide to using the deploydocs function to automatically generate docs and push them to GitHub.

doctest(package::Module; kwargs...)

Convenience method that runs and checks all the doctests for a given Julia package. package must be the Module object corresponding to the top-level module of the package. Behaves like an @testset call, returning a testset if all the doctests are successful or throwing a TestSetException if there are any failures. Can be included in other testsets.


manual controls how manual pages are handled. By default (manual = true), doctest assumes that manual pages are located under docs/src. If that is not the case, the manual keyword argument can be passed to specify the directory. Setting manual = false will skip doctesting of manual pages altogether.

Additional keywords are passed on to the main doctest method.

doctest(source, modules; kwargs...)

Runs all the doctests in the given modules and on manual pages under the source directory. Behaves like an @testset call, returning a testset if all the doctests are successful or throwing a TestSetException if there are any failures. Can be included in other testsets.

The manual pages are searched recursively in subdirectories of source too. Doctesting of manual pages can be disabled if source is set to nothing.


testset specifies the name of test testset (default "Doctests").

doctestfilters vector of regex to filter tests (see the manual on Filtering Doctests)

fix, if set to true, updates all the doctests that fail with the correct output (default false).

plugins is a list of Documenter.Plugin objects to be forwarded to makedocs. Use as directed by the documentation of a third-party plugin.


When running doctest(...; fix=true), Documenter will modify the Markdown and Julia source files. It is strongly recommended that you only run it on packages in Pkg's develop mode and commit any staged changes. You should also review all the changes made by doctest before committing them, as there may be edge cases when the automatic fixing fails.


This module provides APIs for handling documentation metadata in modules.

The implementation is similar to how docstrings are handled in Base by the Base.Docs module — a special variable is created in each module that has documentation metadata.

Public API

Supported metadata

  • DocTestSetup: contains the doctest setup code for doctests in the module.

Returns the documentation metadata dictionary for the module m. The dictionary should be considered immutable and assigning values to it is not well-defined. To set documentation metadata values, DocMeta.setdocmeta! should be used instead.

getdocmeta(m::Module, key::Symbol, default=nothing)

Return the key entry from the documentation metadata for module m, or default if the value is unset.

setdocmeta!(m::Module, key::Symbol, value; recursive=false, warn=true)

Set the documentation metadata value key for module m to value.

If recursive is set to true, it sets the same metadata value for all the submodules too. If warn is true, it prints a warning when key already exists and it gets rewritten.



DocumenterTools.generate(path::String = "docs"; name = nothing, format = :html)

Create a documentation stub in path, which is usually a sub folder in the package root. The name of the package is determined automatically, but can be given with the name keyword argument.

generate can also be called without any arguments, in which case it simply puts all the generated files into a docs directory in the current working directory. This way, if you are already in the root directory of your package, you generally only need to call generate() to generate the documentation stub.

generate creates the following files in path:



path file path to the documentation directory to be created (default is "docs").

Keywords Arguments

name is the name of the package (without .jl). If name is not given generate tries to detect it automatically.

format can be either :html (default), :markdown or :pdf corresponding to the format keyword to Documenter's makedocs function, see Documenter's manual.


julia> using DocumenterTools

julia> DocumenterTools.generate("path/to/MyPackage/docs")
[ ... output ... ]
DocumenterTools.generate(pkg::Module; dir = "docs", format = :html)

Same as generate(path::String) but the path and name is determined automatically from the module.


The package must be in development mode. Make sure you run pkg> develop MyPackage from the Pkg REPL, or Pkg.develop("MyPackage") before generating docs.


julia> using DocumenterTools

julia> using MyPackage

julia> DocumenterTools.generate(MyPackage)
[ ... output ... ]
DocumenterTools.genkeys(; user="$USER", repo="$REPO")

Generates the SSH keys necessary for the automatic deployment of documentation with Documenter from a builder to GitHub Pages.

By default the links in the instructions need to be modified to correspond to actual URLs. The optional user and repo keyword arguments can be specified so that the URLs in the printed instructions could be copied directly. They should be the name of the GitHub user or organization where the repository is hosted and the full name of the repository, respectively.


julia> using DocumenterTools

julia> DocumenterTools.genkeys()
┌ Info: Add the key below as a new 'Deploy key' on GitHub ($USER/$REPO/settings/keys) with read and write access.
└ The 'Title' field can be left empty as GitHub can infer it from the key comment.

ssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 Documenter

[ Info: Add a secure 'Repository secret' named 'DOCUMENTER_KEY' (to$USER/$REPO/settings/secrets if you deploy using GitHub Actions) with value:


julia> DocumenterTools.genkeys(user="JuliaDocs", repo="DocumenterTools.jl")
┌ Info: Add the key below as a new 'Deploy key' on GitHub ( with read and write access.
└ The 'Title' field can be left empty as GitHub can infer it from the key comment.

ssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 Documenter

[ Info: Add a secure 'Repository secret' named 'DOCUMENTER_KEY' (to if you deploy using GitHub Actions) with value:

genkeys(package::Module; remote="origin")

Like the other method, this generates the SSH keys necessary for the automatic deployment of documentation with Documenter from a builder to GitHub Pages, but attempts to guess the package URLs from the Git remote.

package needs to be the top level module of the package. The remote keyword argument can be used to specify which Git remote is used for guessing the repository's GitHub URL.

This method requires the following command lines programs to be installed:

  • which (Unix) or where (Windows)
  • git

The package must be in development mode. Make sure you run pkg> develop pkg from the Pkg REPL, or Pkg.develop("pkg") before generating the SSH keys.


julia> using DocumenterTools

julia> DocumenterTools.genkeys(DocumenterTools)
[Info: add the public key below to with read/write access:

ssh-rsa AAAAB3NzaC2yc2EAAAaDAQABAAABAQDrNsUZYBWJtXYUk21wxZbX3KxcH8EqzR3ZdTna0Wgk...jNmUiGEMKrr0aqQMZEL2BG7 username@hostname

[ Info: add a secure 'Repository secret' named 'DOCUMENTER_KEY' to (if you deploy using Travis CI) or (if you deploy using GitHub Actions) with value:

generate([io::IO = stdout,] root::String;force = false)

This function adds a (unconditional) warning (and noindex meta tag) to all versions of the documentation in root.

force overwrites a previous injected warning message created by this function.

A typical use case is to run this on the gh-pages branch of a package. Make sure you review which changes you check in if you are not tagging a new release of your package's documentation at the same time.