Crossrefs

Regular expression for an @ref link url.

This is used by the XRefResolvers.XRefResolverPipeline, respectively xref_unresolved: as long as the url of the link node still matches XREF_REGEX, the reference remains unresolved and needs further processing in subsequent steps of the pipeline.

crossref(doc)

Traverses a Documenter.Document and process internal links and references.

• Links containing @ref URLs are replaced with their real URLs. This delegates to xref, which in turn delegates to the XRefResolvers.XRefResolverPipeline.
• Links to local (.md) documents are rewritten to link to the corresponding path in the output build.
• For links to local files or images, check that the linked files exist.

find_object(doc, binding, typesig)

Find the included Object in the doc matching binding and typesig. The matching heuristic isn't too picky about what matches and will only fail when no Bindings matching binding have been included.

xref(node, meta, page, doc)

Resolve a MarkdownAST.Link node with an @ref URL.

This delegates to XRefResolvers.XRefResolverPipeline. In addition to forwarding the node, meta, page, and doc arguments, it also passes a slug to the pipeline that any pipeline step can use to easily resolve the link target. This slug is obtained as follows:

• For, e.g, [`Documenter.makedocs`](@ref) or [text](@ref Documenter.makedocs), the slug is "Documenter.makedocs"
• For, e.g, [Hosting Documentation](@ref) or [text](@ref "Hosting Documentation"), the slug is sluggified version of the given section title, "Hosting-Documentation" in this case.

xref_unresolved(node)

checks whether node is a link with an @ref URL. Any step in the XRefResolvers.XRefResolverPipeline should use this to determine whether the node still needs to be resolved.

Parse the link.url field of an @ref link. Returns nothing if it's not an @ref, an empty string the reference link has no label, or a whitespace-stripped version the label.

Resolve @ref links for docstrings.

This runs unconditionally (if no previous step was able to resolve the link), and tries to find a code binding for the given slug, linking to its docstring.

Resolve @ref links for headers.

This runs if the slug corresponds to a known local section title, and resolves the node to link to that section.

Resolve @ref links for issues.

This runs if the slug is "#" followed by one or more digits and tries to link to an issue number using Remotes.issueurl.

The default pipeline for resolving @ref links.

The steps for trying to resolve links are:

• XRefResolvers.Header for links like [Section Header](@ref)
• XRefResolvers.Issue for links like [#11](@ref)
• XRefResolvers.Docs for links like [`Documenter.makedocs`](@ref)

Each step may or may not be able to resolve the link. Processing continues until the link is resolved or the end of the pipeline is reached. If the link is still unresolved after the last step, Documenter.xref issues an error that includes any accumulated error messages from the steps. Failure to resolve an @ref link will fail Documenter.makedocs if it is not called with warnonly=true.

The default pipeline could be extended by plugins using the general Selectors machinery.

Each pipeline step receives the following arguments:

• node: the MarkdownAST.Node representing the link. To resolve the @ref URL, any pipeline step can modify the node.
• slug: the "slug" for the link, see Documenter.xref
• meta: a dictionary of metadata, see @meta block
• page: the Documenter.Page object containing the node
• doc: the Documenter.Document instance representing the full site
• errors: a list of strings of error messages accumulated in the XRefResolverPipeline. If a pipeline step indicates that it might be able to resolve a @ref link (Selectors.matcher is true), but then encounters an error in Selectors.runner that prevents resolution, it should push an error message to the list of errors to explain the failure. These accumulated errors will be shown if (and only if) the entire pipeline fails to resolve the link.

The Selectors.matcher of any custom pipeline step should use Documenter.xref_unresolved to check whether the link was already resolved in an earlier pipeline step.