Cross References


    To link between documentation pages, use the cross reference macro (commonly called an xref) and a page ID. The number of page ID coordinates you need to specify in the xref depends on the location of the current page in relation to the location of the destination page (i.e., the page you want to link to). The closer the two files are, the shorter the page ID.

    To link to a page in the same module as the current page, all you need to know is the file name of the document.

    xref:name-of-file.adoc[link text]

    For example, to link to the AsciiDoc Basics page, a document that is in the same module as this page, Cross References, you write:

    xref:basics.adoc[This links to the AsciiDoc Basics page].

    And this is the result:

    Link to a page in a topic folder
    xref:concept/index.adoc[Key Concepts]
    Link to a page in the same module but in a different version
    xref:3.3@error-handling.adoc#message-list[error messages]

    To link to a page in the same component as the current page, but in a different module, you need to know the file name of the document and the module name. The module name is the name of the top-level folder in the modules directory the document is stored in.

    xref:module-name:name-of-file.adoc[link text]

    For example, to link to the document index.adoc, which is in the same component as this page but stored in the ROOT module, you write:

    Let's go to the xref:ROOT:index.adoc[documentation home page].

    This renders as:

    Let’s go to the documentation home page.

    Link to a Page in a Different Component

    To link to a page in a different component, you need to know the destination component’s name, module name, and file name.

    xref:component-name:module-name:name-of-file.adoc[link text]

    The component’s name is located in the component descriptor file, antora.yml, which is found in the destination component’s repository.

    antora.yml in docs-server repository
    name: server (1)
    title: Couchbase Server
    version: '5.5'
    start_page: introduction:intro.adoc
    - modules/ROOT/nav.adoc
    1 Component name that you use in xrefs.

    To link from this page, to the What’s New? page in the server component, you write:

    xref:server:introduction:whats-new.adoc[What's new] in Couchbase Server?

    This renders as:

    What’s new in Couchbase Server?

    To link to a specific element in another page, you need to know the element’s ID. Add a hash (#) directly after the file name, followed by the ID of the element. For example, to link from this page to the Images section on the AsciiDoc Basics page, you write:

    See xref:basics.adoc#images[Images].

    This renders as:

    See Images.

    Cross Reference Best Practices

    • Create attributes for long page ID coordinates to improve the source readability for other contributors.

    • Create attributes for page ID coordinates used several times on the same page.

    Learn More