Commit fa1cdb70 authored by Sarah White's avatar Sarah White

add cross reference documentation

- change reference topic to cross-reference
- add page to page xref file
- add same page xref file
- add xref files to nav
- add xrefs between navigation pages and cross reference pages
parent 8960c853
= Reference a Section, Block, Line or Word
ifndef::env-site,env-github[]
include::_attributes.adoc[]
endif::[]
// Settings
:idprefix:
:idseparator: -
// URLs
:uri-adoc-manual: http://asciidoctor.org/docs/user-manual
//WARNING: Don't use the `link` macro for referencing sections and IDs in the same page.
== Reference a section in the same page
Section title IDs are automatically generated when AsciiDoc pages are processed, so you can use them as links by referencing the section's title.
However, the title must begin with an uppercase letter (in basic Latin) without any leading formatting marks.
To link to the beginning of a section in the same page, use the in-page cross reference which is designated by a set of double angled brackets (`<< >>`).
.Link to section title in the same page
[source,asciidoc]
----
This is an in-page cross reference: <<Reference a section in the same page>>. //<1>
This is an in-page cross reference:
<<reference-a-section-in-the-same-page,Check it out>>! //<2>
----
<1> In-page xref to a section using the section's title.
<2> In-page xref to a section using the section's implicit ID.
== Reference a block, line, or word in the same page
To link to a block or line in the same page, you must define an ID at that location.
.Create an ID
[source,asciidoc]
----
[#playbook] //<1>
Here's an example of a playbook.
This is an [#name-me] inline ID. //<2>
----
<1> An ID can be placed on a paragraph (i.e., block).
<2> An ID can be placed inline.
There are some exceptions, see {uri-adoc-manual}/#anchordef[defining an anchor] in the Asciidoctor user manual for more use cases.
To link to that ID, use the same in-page xref markup you use for section headings.
.Link to an ID
[source,asciidoc]
----
We'll walk through a <<playbook,detailed example>> of a playbook in this tutorial.
----
Reference: {uri-adoc-manual}/#anchordef[Define an anchor]
= Reference another Page
ifndef::env-site,env-github[]
include::_attributes.adoc[]
endif::[]
// Settings
:idprefix:
:idseparator: -
Antora uses an enhanced version of the AsciiDoc inline xref macro for linking between pages in a site.
You'll also use this xref macro to add pages to xref:navigation:linked.adoc[navigation files].
//This feature is activated if the value of the macro target ends with the AsciiDoc file extension (`.adoc`) or a fragment identifier (`#id`).
The information you need to provide in the xref macro depends on the location of the current file and the location of the destination file (the document you're linking to).
The closer the two files are, the less information you need to specify.
== Page reference structure
First, let's dissect a fully qualified page reference:
[source,asciidoc]
----
xref:version-name@component-name:module-name:local-path.adoc#fragment[link text]
----
Here's what each part of the page reference does:
xref: ::
The prefix for an AsciiDoc inline xref macro.
version-name@ ::
If a component has versions, the first target position is used to specify the version name of the destination component.
This value is defined in the antora.yml file in the branch of the component repository that hosts the destination file.
When the version target is filled, it must be directly followed by an `@` symbol.
component-name: ::
The second target position specifies the name of the destination component.
The component name is directly followed by one colon (`:`).
This value is defined in the name key of the antora.yml file in the branch of the component repository that hosts the destination file.
If a component name is present in the xref, a module name must also be specified after the `:`.
Otherwise, this position gets interpreted as the module name.
module-name: ::
The third target position specifies the name of the destination module.
The module name is directly followed by one colon (`:`).
If a component name is present, and the name of the module is "`ROOT`", the module name position can be left empty in some cases.
That's why sometimes you see a component name followed by two colons (`::`).
local-path.adoc ::
The fourth target position specifies the local path of the destination file relative to the module's documents directory.
This value may include one or more optional topic folders.
The destination file name must have the _.adoc_ file extension.
#fragment ::
An optional ID of a section or other anchor point to link to in the destination page (i.e., deep link).
This part is always optional.
[link text] ::
The text of the link that is displayed to the user.
This text must be entered inside a set of square brackets (`[]`) at the end of the macro.
If the text is not specified, the raw target is used.
[link text,aspect=name-of-aspect] ::
To link to the aspect variant of a page, add the aspect attribute after the link text.
A comma (`,`) should directly follow the link text, and the aspect attribute should directly follow the comma, i.e., don't add a blank space after the comma.
To learn more about referencing aspect pages, go to the xref:apect-page-link.adoc[referencing an aspect page].
== Scenario: In the same component and module
When the current document and the destination document are in the same module, you only need to enter the name of the destination file.
.Link to a document in the same module
[source,asciidoc]
----
xref:error-handling.adoc[Error Handling]
----
.Link to a document in a topic folder
[source,asciidoc]
----
xref:concept/index.adoc[Key Concepts]
----
.Link to a document in the same module and in a different version
[source,asciidoc]
----
xref:3.3@error-handling.adoc#message-list[error messages]
----
== Scenario: In the same component but different module
When the current document and the destination document are in the same component but different modules, you'll need to enter the name of the destination module and destination file.
.Link to a document in another module
[source,asciidoc]
----
xref:getting-started:implement-and-test-api.adoc[implement an API]
----
.Link to a document in the ROOT module and in a topic folder
[source,asciidoc]
----
xref:ROOT:transports/ajax-reference.adoc[Ajax Transports]
----
.Link to a document in the ROOT module and in a different version
[source,asciidoc]
----
The xref:3.4@ROOT:scopes/foreach.adoc[foreach scope] splits a collection.
----
== Scenario: In a different component
When the current document and the destination document are in different components, you'll need to enter values for all of the target positions.
If a version is not specified in this scenario, the implicit value is `master@`.
.Link to a document in the ROOT module of a versioned component
[source,asciidoc]
----
How do I xref:2.0@default-ui::modify-template.adoc[modify a template] in the UI project?
----
.Link to a document in the ROOT module of a component that doesn't have versions
[source,asciidoc]
----
xref:icons::index.adoc#intro[Introducing the Icon Project]
----
.Link to a document in a module of a component that doesn't have versions
[source,asciidoc]
----
xref:icons:web:modify-svg.adoc[Getting started with the SVG assets]
----
......@@ -5,5 +5,7 @@
* xref:install-prerequisites.adoc[Install Prerequisites]
** xref:troubleshoot-yarn-nodegit.adoc[Troubleshoot Yarn and NodeGit]
* xref:run-antora-and-generate-site.adoc[Run Antora]
* Page References
** xref:reference/aspect-page.adoc[Reference an Aspect Page]
* Cross References
** xref:cross-reference/page-to-page-link.adoc[Link to a Page]
*** xref:cross-reference/in-same-page-link.adoc[Link in the Same Page]
** xref:cross-reference/aspect-page-link.adoc[Link to an Aspect Page]
......@@ -33,7 +33,7 @@ You can use the AsciiDoc include directive in an aspect navigation file.
The include file must reside in the playbook repository and is resolved relative to the file that references it.
The basename of the navigation file (minus the file extension) is used as the name of the aspect domain.
You'll use this name to create a reference to an xref:ROOT:reference/aspect-page.adoc[aspect page] from outside of the aspect domain.
You'll use this name to create a reference to an xref:ROOT:cross-reference/aspect-page-link.adoc[aspect page] from outside of the aspect domain.
Here's an example of a navigation file for an aspect domain named `hello-app`:
......@@ -94,6 +94,7 @@ site:
Let's dive into more detail about what goes in the aspect navigation file.
== The contents of an aspect navigation file
// This section needs serious clarification or it can be easily confused with how to do apect page xrefs from page to page
The items in an aspect navigation file are predominantly cross references to pages within the site.
The aspect navigation file not only defines the navigation used for an aspect domain, it also enlists each page referenced in the aspect domain, creating what is referred to as an [.term]_aspect page_.
......
......@@ -46,8 +46,8 @@ The list can have a block title.
<5> List item with external link
The items in a linked navigation file are usually cross references to pages in the same module.
// relink xref page-references,appropriate inline xref macro patterns
However, using the appropriate inline xref macro patterns, you can include references to any document in the site, whether it's stored in the same module or not.
However, using the xref:ROOT:cross-reference/page-to-page-link.adoc[appropriate inline xref macro patterns], you can include references to any document in the site, whether it's stored in the same module or not.
// relink xref <<ex-links,external links>>
You can also include external links, such as pass:[https://support.example.com], and normal (i.e. unlinked) text.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment