Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Cross References

      +

      To create links between pages inside the Couchbase Documentation, you must use the cross reference (xref) macro.

      You need the resource ID of the page you want to link to before you can create an xref. The number of attributes you need to specify in the resource ID depends on where the page you want to link to is located in relation to your current page. Closer pages need fewer attributes.

      For a good overview about resource IDs, see the Antora documentation.

      To understand some of the key terms associated with resource IDs and creating xrefs, see About Couchbase Documentation Repositories.

      Link to a Page in the Same Module

      A page is in the same module as another page if they’re in the same <module-name>/pages folder.

      To link to a page in the same module as the current page, all you need to know is the page’s filename.

      Start with the xref: macro, and add the full filename, including the extension. End with a set of square brackets ([]). Put text inside the square brackets to add link text, or leave it blank to use the title of the file.

      For example:

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

      To use an example from this Writer’s Guide, to link to the basics.adoc file, which is in the same module as this page on cross references, you would write:

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

      It would render in the finished documentation as:

      This links to the AsciiDoc Basics page.

      Link to a Page in the Same Module But in a Topic Folder

      If you want to link to a page that’s inside a topic folder, or a subfolder of the <module-name>/pages folder, you just need to add the folder name, followed by a backslash (/) in front of the file name.

      For example:

      xref:concept/index.adoc[Key Concepts]

      Link to a Page in the Same Module But in a Different Version

      If you want to link to a page that’s inside the same <module-name>/pages folder but in a different version of the documentation, add the version number, followed by an @, in front of the filename.

      For example:

      xref:3.3@error-handling.adoc#message-list[error messages]

      Link to a Page in a Different Module But the Same Component

      To link to a page in the same component as the current page, but in a different module, you need to know the filename of the page and the module name.

      Add the module name (folder name), followed by a colon (:), in front of the filename.

      For example:

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

      To use an example from this Writer’s Guide, to link to the index.adoc file in the ROOT module, you would write:

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

      It would render in the finished documentation 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 page’s component name, module name, and filename:

      • Start with the component name, followed by a colon (:).

      • Add the module name, followed by a colon (:).

      • Add the filename, including the file extension.

      For example:

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

      If you’re not sure of the component name for your xref, you can check the antora.yml file inside the Documentation repository that holds that file.

      The antora.yml should always be found in the top-most level of the repository’s files. Look for the name attribute inside the antora.yml file.

      The following is an example antora.yml file for version 5.5 of the Couchbase Server documentation:

      name: server
title: Couchbase Server
version: '5.5'
start_page: introduction:intro.adoc
nav:
- modules/ROOT/nav.adoc

      The name attribute is server.

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

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

      It would render in the finished documentation as:

      What’s new in Couchbase Server?

      You can link to a specific element, such as a heading, table entry, and more, by assigning or knowing that element’s ID and adding it to your xref.

      This is known as an anchor link.

      After the filename and extension, add a hash (#), then the element ID.

      For example, you can link from this page to the Images heading in the AsciiDoc Basics page by writing:

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

      The heading in the AsciiDoc Basics page looks like this in the source AsciiDoc file:

      Images

      The xref would render in the finished documentation 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.

      • Make sure to always assign link text to xrefs when linking to an element on a page with an anchor link. Try to write good link text.

      • Leave the link text blank when you’re not linking with an anchor link. This keeps link text up-to-date and accurate if a page title changes.

      Learn More

      Additional Resources