Documenter, if set up appropriately, can automatically generate links to publicly hosted Git repositories (such as source and edit links to e.g. repositories hosted on GitHub). Usually this is for linking back to the main package repository or the project source code.
Remotes API is used to specify remote repositories and generate the URLs. It is also designed to be extended, to support additional Git repository hosting services.
There are two categories of remote repositories that (may) need to be configured for Documenter to be able to determine remote URLs:
Project repository remote, specified with the
makedocs. This refers to the project as a whole (rather than specific files), and is used for the repository landing page link, issue references etc.
File link remotes, specified by the
makedocs. These are used to link a file system file to the corresponding file in the remote repository. In particular, these are used to generate the edit links for manual pages, and Julia source file links for docstrings.
For the most common case – a repository of a simple Julia package – there is usually only one remote repository that one links to, and the distinction between file links and repository links is not relevant. However, in more complex setups it may be necessary to distinguish between the two cases. The defaults to the two keywords try to cater for the most common use case, and as is explained below, this means that there has to be some interaction between these two arguments.
When Documenter has to determine the URL of a file in the hosted repository, it gets a local filesystem absolute path as an input. In the case of Markdown files, those local paths are determined by
makedocs when it reads them. The links to Julia files are determined from the docsystem, and point to where the code was loaded from (e.g. for a development dependency of the environment, they come from the
Pkg.developed path; but for normal
Pkg.add dependencies the source files are usually in
In most cases, for both Markdown and Julia files, the files Documenter is concerned about are located in the currently checked out Git repository that contains the Documenter
make.jl script (e.g. the locally checked out package repository). However, sometimes they may also be in a different repository (either in a subdirectory of or outside of the primary repository), or even in a non-Git directory outside of the primary repository (e.g. if you're trying to build the documentation of a release tarball).
To handle those cases, the
remotes keyword to
makedocs can be used to set up a
local directory => remote repository mapping for local file system paths. The local directory is assumed to correspond to the root of the Git repository, and any subpath within that directory is then resolved to the corresponding path in the remote repository. If there are nested
remotes configured, Documenter will use the one that matches first as it walks up the directory tree from the original path.
As the common cases are a locally checked out Git repository (added with
Pkg.develop to the docs environment), or a released package which is hosted on GitHub (
Pkg.added to the environment), Documenter will also try to determine such remotes automatically.
- When Documenter walks up the directory tree, it checks whether the directory is a root of a Git repository (by looking for the presence of a
.gitdirectory or file). Once it finds a valid local repository root, it tries to read its
- If that matches a GitHub repository, Documenter automatically sets up a mapping from that directory, and then uses that to determine the remote URLs.
- If Documenter is unable to determine the remote from the repository's
originis not set up, or it is hosted somewhere else), it will error, as it will not be able to determine the remote URLs. In this case, the remote should be configured explicitly with
You can think of it as Documenter automatically populating
remotes with any cloned GitHub repositories it finds.
For released packages (those added using
Pkg.add(...) rather than
Pkg.develop(...)), the version and repository can be determined from the package metadata, but a commit hash is not readily available. In this case, Documenter will guess that a tag
v$VERSION exists in the repository on GitHub. Note that these tags are created automatically by the widely used JuliaRegistries/TagBot action. Since this is sometimes not the case, and could cause dead or incorrect links, setting the
linkcheck keyword to
makedocs will check these guessed links have an existing target and that the existing target matches the published package. (Note this will also all other external links from your documentation.) Note that enabling this option can cause documentation builds to fail due to network errors or intermittent downtime of external services.
Since Documenter is primarily used to generate documentation for Julia packages, there is some interaction between the
remotes keyword arguments, to automagically determine their defaults. This means that usually it is not necessary to specify either explicitly in the
The rules are as follows:
repois not specified, it is essentially determined like any other remote link, by trying to figure out the repository that contains the
rootpath argument of
makedocs(defaulting to the directory of the
make.jlscript; usually the
Remoteobject will one of the
remotes, which in turn may have been determined automatically via the
originURL of the containing Git repository.
repois specified, but the
remotesfor the repository root is not,
repowill function as a
remotesentry for the repository root. This is so that it would not be necessary to specify the same argument twice (i.e. once for general repository links, once for file links).
remotesfor the repository root are configured, Documenter will throw an error, as it does not really make sense for them to point to two different remotes.
Types and functions for handling repository remotes.
GitHub(user :: AbstractString, repo :: AbstractString)
GitHub(remote :: AbstractString)
Represents a remote Git repository hosted on GitHub. The repository is identified by the names of the user (or organization) and the repository:
GitHub(user, repository). E.g.:
repo = GitHub("JuliaDocs", "Documenter.jl")
The single-argument constructor assumes that the user and repository parts are separated by a slash (e.g.
GitLab(host, user, repo)
Represents a remote Git repository hosted on GitLab. The repository is identified by the host, name of the user (or organization), and the repository. For example:
repo = GitLab("JuliaDocs", "Documenter.jl")
The single argument constructor assumes that the end user and repository parts are separated by a slash (e.g.,
The following types and functions and relevant when creating custom
abstract type Remote
Abstract supertype for implementing additional remote repositories that Documenter can use when generating links to files hosted on Git hosting service (such as GitHub, GitLab etc). For custom or less common Git hosting services, the user can create their own
Remote subtype and pass that as the
repo argument to
When implementing a new type
T <: Remote, the following functions must be extended for that type:
Additionally, it may also extend the following functions:
Remotes.repourl(remote::T) -> String
An internal Documenter function that must be extended when implementing a user-defined
Remote. It should return a string pointing to the landing page of the remote repository. E.g. for
GitHub it returns
Remotes.fileurl(remote::T, ref, filename, linerange) -> String
An internal Documenter function that must be extended when implementing a user-defined
Remote. Should return the full remote URL to the source file
filename, optionally including the line numbers.
refis string containing the Git reference, such as a commit SHA, branch name or a tag name.
filenameis a string containing the full path of the file in the repository without any leading
linerangeeither specifies a range of integers or is
nothing. In the former case it either specifies a line number (if
first(linerange) == last(linerange)) or a range of lines (
first(linerange) < last(linerange)). The line information should be accessed only with the
lastfunctions (no other interface guarantees are made).
nothing, the line numbers should be omitted and the returned URL should refer to the full file.
It is also acceptable for an implementation to completely ignore the value of the
linerangeargument, e.g. when the remote repository does not support direct links to particular line numbers.
GitHub, depending on the input arguments, it would return the following strings:
An internal Documenter function that can be extended when implementing a user-defined
Remote. It should return a string with the full URL to an issue referenced by
nothing if it is not possible to determine such a URL.
issuenumberis a string containing the issue number.
It is not mandatory to define this method for a custom
Remote. In this case it just falls back to always returning
issuenumber = "123", it would return
- 1There is an exception to this: links to Julia
Basemodule source files. But Documenter already known how to handle those correctly, and they are really only relevant to the Julia main manual build.
- 2GitHub is the most common case, but this could be extended to cover other Git hosting services in the future (as long as the remote can reliably determined from the
- 3One thing to be aware here is that Documenter builds up a cache of the Git repositories it finds on every
makedocscall. This is for performance reasons, to reduce the number of file system accesses and, in particular,
gitcalls, which are relatively slow.
- 4If there is a use case for this, this limitation could be relaxed in the future.