Commit 74e6be1f by Sarah White

merge !135

resolves #76 add page id and xref macro images
parents 967bfeeb 27afb502
Pipeline #17542310 passed with stages
in 4 minutes 6 seconds
......@@ -96,21 +96,9 @@ These items may or may not be broken down by OS, depending on whether or not the
+
_{s}_ Accepted
Installation (SC, P)::
_{r}_ Clear, straight-forward instructions for installing Antora on an OS.
+
_{s}_ Accepted
Assumptions (P#)::
_{r}_ Probably a section of the Installation page.
Reminds the user about the requirements/steps they should have already completed.
+
_{s}_ Under consideration
Download and Install (P)::
_{r}_ Instructions for downloading and installing Antora on an OS.
Page may be broken into a section for Linux, macOS, and Windows.
Page and/or each section will also include instructions on how to verify Antora installed and link to how to test the installation using the demo.
Install Antora (P)::
_{r}_ Clear, straight-forward instructions for installing Antora.
Includes Assumptions section: Reminds the user about the requirements/steps they should have already completed.
+
_{s}_ Accepted
......@@ -314,6 +302,11 @@ Types include documentation (single, assembled from partials, combo), home/start
+
_{s}_ Accepted
Page ID (P)::
_{r}_ The role of the page ID, its structure, and why it is important in Antora.
+
_{s}_ Accepted
Page and UI interactions (P)::
_{r}_ Overview of how each page type and a UI template merge and what the user needs to consider (if anything).
+
......
......@@ -31,3 +31,4 @@
.xref:pages.adoc[Pages]
* xref:create-standard-page.adoc[Create a Standard Page]
* xref:page-id.adoc[Page ID]
......@@ -14,7 +14,7 @@ This file serves two purposes:
This ability to "`start`" a documentation component anywhere in a directory hierarchy allows you to store a component in a repository with the software it documents, with a demo project, by itself, etc.
. *Component information*: [.path]_antora.yml_ is a component descriptor file.
It associates the files under this hierarchy with the specified component name and version (aka component version), decoupling the files from the repository and branch in which they live.
It associates the files under this hierarchy with the specified component name and version (aka component-version), decoupling the files from the repository and branch in which they live.
This information is used for creating links to pages in this component.
The file also identifies files to use for site navigation.
......@@ -47,15 +47,16 @@ nav: # <5>
- modules/module-three/nav.adoc
- ...
----
<1> Name key and value
<2> Title key and value
<3> Version key and value
<4> Start page key and value
<5> Nav key and values
<1> Name key
<2> Title key
<3> Version key
<4> Start page key
<5> Nav key
[#name-key]
=== name
The value of the name key is the component name that is used when the component is referenced in a xref:asciidoc:page-to-page-xref.adoc#page-id-cname-def[page ID].
The value of the name key is the component name that is used when the component is referenced in a xref:asciidoc:page-to-page-xref.adoc#page-id-cname-def[cross reference].
The value can contain letter, number, underscore (`+_+`), hyphen (`-`), and period (`.`) characters.
=== title
......@@ -68,19 +69,19 @@ This includes:
* domain selector drawer
* first breadcrumb position
[#version-key]
=== version
The value of the version key is both the display version and the actual version of the component.
It's used anywhere that the version is referenced or identified.
The value of the version key is both the display name and version coordinate.
This includes:
* page ID (xref:asciidoc:page-to-page-xref.adoc#page-id-vname-def[version-name@])
* page ID and cross references (xref:asciidoc:page-to-page-xref.adoc#page-id-vname-def[version@])
* domain selector menu
* domain selector drawer
* page version selector
* edit page URI (not visible)
The key's value can contain letter, number, period (`.`), underscore (`+_+`), and hyphen (`-`) characters.
The value can contain letter, number, period (`.`), underscore (`+_+`), and hyphen (`-`) characters.
If the value starts with a number, it must be contained within a set of single quote marks (`'`).
.Example version key values
......@@ -93,9 +94,9 @@ If the value starts with a number, it must be contained within a set of single q
By default, Antora automatically uses the file [.path]_index.adoc_ in the ROOT module of a component as the start page of that component (i.e., _pass:[https://company.com/docs/component/]_).
If a component doesn't have an [.path]_index.adoc_ file, then the `start_page` key must be set in the component's [.path]_antora.yml_ file and assigned a file to use as the component's start page.
The value uses the page ID structure.
and must specify the module and path to the file.
If a component doesn't have an [.path]_index.adoc_ file, then the `start_page` key must be set in the component descriptor file and assigned a page to use as the component's start page.
The value uses the xref:page-id.adoc[page ID structure]
and must specify the module and page coordinates of the file.
.Start page value examples
[source,yaml]
......
= Page Identifier
ifndef::env-site,env-github[]
include::_attributes.adoc[]
endif::[]
// Settings
:idprefix:
:idseparator: -
//Antora's page IDs are one of its foundational elements.
== What is a page identifier?
In order for a page to be linked to, i.e., referenced, that page must have a unique and stable identifier.
This identifier is like your mobile phone number.
When someone calls your mobile number, they know they're calling you and that they'll reach your phone no matter where your phone is located.
So, when an identifier is "`called`", the page that is connected to that identifier answers, no matter where it's published.
We call a page's "`number`" a page identifier, or page ID for short.
[#structure]
== How is a page ID structured?
The page ID is unique and stable because it is constructed from the properties of the source document.
A page ID is based on a documentation component's xref:component-structure.adoc[standard project structure].
Documentation components ensure that each page lives in a defined, describable location.
From this structure, each location derives unique, reliable coordinates we can use to refer to it.
These source document coordinates are described below.
Version::
The version of the component in which the page lives; often mapped to a repository branch.
Component::
The documentation component to which the page belongs; often mapped to a repository.
Module::
The content bundle in which the page is grouped; if empty, defaults to ROOT.
Page::
The path to the page's source file in the module, including any leading topic directories.
Fragment::
The identifier of an element inside a page, i.e., deep link.
These coordinates are organize in a standard structure to create a unique, fully-qualified page ID.
image::page-id-anatomy-diagram.svg[Page ID anatomy,role=grow-x]
For example, this is the fully-qualified page ID for this page.
[source,asciidoc]
1.0@antora:ROOT:page-id.adoc
== How is a page referenced with its ID?
A page ID is used in an AsciiDoc cross reference, also called an xref, to link one documentation page to another documentation page.
image::xref-macro-anatomy-diagram.svg[Page reference anatomy,role=grow-x]
Here's how that looks in practice:
[source,asciidoc]
Learn all about xref:1.0@antora:ROOT:page-id.adoc[page IDs].
Specifying the version, component, and even module every time seems like overkill, right?
Don't worry, there's a shorthand.
For instance, if you're linking to a page in the same module as the page you're linking from, all you need to do is specify the `page` coordinate.
The next example shows a cross reference from this page ([.path]_page-id.adoc_) to the [.path]_create-standard-page.adoc_ page.
Both of these pages live in the same component and module.
[source,asciidoc]
Let's create a xref:create-standard-page.adoc[new page].
A whole range of examples, from linking between different components to linking to different versions of a page, are explained in xref:asciidoc:page-to-page-xref.adoc[page cross references].
[#important]
== Why are page IDs important?
*We've avoided coupling to the published URL* by using a source-to-source reference.
Notice the page coordinate ends with [.path]_.adoc_, the file extension of an AsciiDoc source file.
Regardless of whether you're deploying your site locally, to a staging or production environment, or you change URL strategies, the page ID always remains the same.
The cross reference locks on to the target page and produces a URL that points to it wherever it gets published.
*We've avoided coupling to the filesystem* by using a location based on the documentation component structure.
The page ID describes the source file's project (component-version) and where in that project the source file is located (module-page).
*We've eliminated the relative path (../../) problem* by specifying the page as a module-relative path.
The path always starts from a module's [.path]_pages_ directory, even when the referencing page is located inside a topic folder.
If you move or rename a page within a module, you don't have to change any references to other pages.
*This human-friendly referencing system saves you from having to do computations in your head while writing*.
You just specify the coordinates of the page you want to reference.
There's no need to worry about the source file's physical location on disk or its published URL.
All you need to know are the names of your components, versions, modules, and pages so you can fill in this information.
////
This needs to go in a section about future development.
Of course, inbound references to the page you move do have to be updated.
To counter this, you could pin the page ID of the page you want to move, thus adding more stability.
That way, references to the page don't have to be updated even when it moves.
Though, a little help from the text editor to "`refactor`" references could make this abstraction unnecessary.
*We've made it possible to validate and update references* by using a well-defined pattern that's easy for a script to locate, parse, and rewrite.
////
......@@ -7,49 +7,53 @@ endif::[]
:idseparator: -
:colon: :
Antora uses an enhanced version of the AsciiDoc cross reference macro, commonly referred to as an xref, for linking between pages in a site.
This xref macro is also used to add pages to xref:navigation:create-a-navigation-file.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`).
To link between documentation pages, you'll use the the AsciiDoc cross reference macro and a page ID.
This syntax in also used to add pages to xref:navigation:create-a-navigation-file.adoc[navigation files].
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.
== Reference by page ID
== Cross reference structure
In Antora, a cross reference, also called an xref, needs a page ID in order to link to another documentation page.
The number of page ID coordinates you need to enter into the xref 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 shorter the page ID.
First, let's dissect a fully qualified cross reference:
In the next section, will go over each part of the xref and page ID syntax.
[source,asciidoc]
----
xref:version-name@component-name:module-name:page.adoc#fragment[link text]
----
NOTE: The page ID is integral to Antora's ability to publish a site to multiple environments and domains without you needing to modify your source content.
If you want to learn more about the page ID, see xref:ROOT:page-id.adoc#important[Why are page IDs important?]
== Xref and page ID anatomy
Let's dissect a cross reference with a fully-qualified page ID.
image::xref-macro-anatomy-diagram.svg[Page reference anatomy,role=grow-x]
Here's what each part of the cross reference does:
Here's what each part of the cross reference and page ID does:
xref{colon}::
The prefix for an AsciiDoc source file-to-file cross reference macro.
The prefix of the AsciiDoc source file to source file cross reference macro.
[#page-id-vname-def]
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 xref:ROOT:antora_yml.adoc[component descriptor file] ([.path]_antora.yml_) 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.
version@::
The first page ID coordinate is used to specify the version name of the destination component.
This value is defined in the xref:ROOT:component-descriptor.adoc#version-key[component descriptor file] ([.path]_antora.yml_) in the branch of the component repository that hosts the destination file.
When the version coordinate is filled, it must be directly followed by an at sign (`@`).
[#page-id-cname-def]
component-name{colon}::
The second target position specifies the name of the destination component.
The second coordinate 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 [.path]_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.
This value is defined in the xref:ROOT:component-descriptor.adoc#name-key[name key] of the component descriptor in the branch of the component repository that hosts the destination file.
If a component name is present, a module name must be specified after the `:`.
Otherwise, this coordinate gets interpreted as the module name.
module-name{colon}::
The third target position specifies the name of the destination module.
The third coordinate 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 (`::`).
That's why you see a component name followed by two colons (`::`) sometimes.
page.adoc::
The fourth target position specifies the local path of the destination file relative to the module's documents directory.
The fourth coordinate 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.
......@@ -87,13 +91,13 @@ xref:3.3@error-handling.adoc#message-list[error messages]
== Scenario: In the same component but a different module
When the current page and the destination page are in the same component but different modules, you'll need to enter the name of the destination module and destination file.
When the current page and the destination page are in the same component but different modules, you'll enter the name of the destination module and destination file.
.Link to a page in another module
[source,asciidoc]
xref:get-started:implement-api.adoc[implement an API]
.Link to a page in the ROOT module and in a topic folde
.Link to a page in the ROOT module and in a topic folder
[source,asciidoc]
xref:ROOT:transports/c04-reference.adoc[C04 Transports]
......@@ -103,8 +107,8 @@ The xref:3.4@ROOT:scopes/super-mass.adoc[super massive scope] splits atoms.
== Scenario: In a different component
When the current page and the destination page 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@`.
When the current page and the destination page are in different components, you'll enter values for all of the coordinates.
If a version is not specified, the implicit value is `master@`.
.Link to a page in the ROOT module of a versioned component
[source,asciidoc]
......
......@@ -101,7 +101,7 @@ For current docs.antora.org tasks, see the site {uri-docs-site-issues}[issue tra
* [ ] Document UI bundle configuration features {uri-issues}/152[#152]
* [x] _Docs Site:_ Set up supplemental UI files {uri-docs-site-issues}/4[#4]
* [ ] _Docs Site:_ Connect Docs and project sites
* [ ] Add page ID and xref anatomy diagrams {uri-issues}/76[#76]
* [x] Add page ID and xref anatomy diagrams {uri-issues}/76[#76]
* [ ] Add how to create a partial page
==== Waiting
......
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