Cross Referencing

You may want to reference different parts of your document from other places in it. Publish supports this with a simplified version of Documenter.jl’s syntax. You can do this by writing markdown link syntax.

File References

When you reference a relative path to another file within a project the resulting link in the final document will point to the generated file rather than the original.

A [link](../file.md)

The above link will reference the resulting content generated by file.md. So either a file.html or a particular page within the generated PDF.

Direct and Indirect Smart References

Smart references determine the location within a project that you would like to link to without having to explicitly write out the file paths.

There are two kinds of smart reference links. Direct are those that are determined from the visible text of a link and indirect ones that use the “title” text of a link to determine the destination instead.

All smart references use a single # as the link destination, i.e.

A [direct link](#) and an [indirect link](# "actual link").

In the above example the first link is a direct link since it does not provide a link title. The second one is an indirect link since it does provide a title, "actual link", and so that text is used to determine the link destination instead of the text indirect link.

Referencing Headings

To refer to a heading somewhere else in the project it must be uniquely named — specifically the “slug” generated by the heading text must be unique.

Typically referencing a heading is as simple as placing the text of the heading as link text, or link title, and everything is calculated for you. In cases where you have multiple headings within your document that contain the same text you’ll need to use the IDs instead, as explained in the next section

Referencing IDs

Each heading within a page is given a unique ID associated with it. This is what is used in the previous section to determine destinations. You can also assign your own special ID to individual markdown elements, most commonly headings, but also any other node type will do.

{#special-name}
# Generic Heading Name

Above we give a #special-name to the heading since it’s got a generic name that appears elsewhere in the project. This allows us to refer to it from other places in the document using either a direct or indirect reference as discussed above. For example

A [link](# "special-name").

A [special-name](#).

Referencing Docstrings

If you’re writing the documentation for a Julia package then you probably have some docstrings. Referencing them can be done in a similar way to the above referencing of headings and IDs. The only difference is that the text is wrapped in backticks, since it represents “code”.

A [`docstring`](#), and an [indirect](# "`docstring`").