Doc reference edits

Signed-off-by: Michal Maléř <[email protected]> Docummenting ways for in-file and cross-file navigation Signed-off-by: Michal Maléř <[email protected]> Review Signed-off-by: Michal Maléř <[email protected]>
quarkusio · Mar 27, 2023 · 2bb430f · 2bb430f
1 parent 32ec9f6
commit 2bb430f
Show file tree

Hide file tree

Showing 6 changed files with 305 additions and 6 deletions.
diff --git a/docs/src/main/asciidoc/_templates/template-concept.adoc b/docs/src/main/asciidoc/_templates/template-concept.adoc
@@ -32,6 +32,51 @@ include::{includes}/extension-status.adoc[]
 - xref:{doc-guides}/doc-concept.adoc#concept[Quarkus documentation content types: Concept guides]
 - xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]
 
+== Anchors for in-file and cross-file navigation
+
+* To create an anchored ID, use lower-case characters, Separate each word with `-` and enclose the ID in `[[]]` as in the example below.
++
+[source,asciidoc]
+----
+[[title-heading]]
+== Title heading
+----
+
+* To call an anchor created in the same file, insert the anchored ID in a `<<>>` xref macro.
++
+[source,asciidoc]
+----
+<<title-heading>>
+----
+
+* To create an anchor with a custom URL caption example, specify the anchored ID and desired name separated by `,` without white space.
++
+[source,asciidoc]
+----
+<<title-heading,Title heading description that fits the context of your content>>
+----
++
+WARNING: Do not use the <<>> format with the verbatim heading or section description, such as
+<<Title heading>>.
+
+* To call an anchored ID from a different file, use the full file name and anchored ID separated by `#`,
+and specify the human-readable URL caption.
++
+[source,asciidoc]
+----
+xref:<other-file-name>.adoc#title-heading[Title heading]
+----
+
+
+* To refer to another file, use the xref macro with the full file name syntax.
+Specify the human-readable URL caption.
++
+[source,asciidoc]
+----
+xref:<name-of-the-file>.adoc[Human-readable label]
+----
+
+
 == Guidelines for a good Concept doc
 
 Explanation/Concept documents should do things that the other parts of the documentation do not.

diff --git a/docs/src/main/asciidoc/_templates/template-howto.adoc b/docs/src/main/asciidoc/_templates/template-howto.adoc
@@ -36,6 +36,50 @@ Your user will also be in the middle of something: define the starting-point tha
 - xref:{doc-guides}/doc-concept.adoc#howto-guide[Quarkus documentation content types: How-to guides]
 - xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]
 
+== Anchors for in-file and cross-file navigation
+
+* To create an anchored ID, use lower-case characters, Separate each word with `-` and enclose the ID in `[[]]` as in the example below.
++
+[source,asciidoc]
+----
+[[title-heading]]
+== Title heading
+----
+
+* To call an anchor created in the same file, insert the anchored ID in a `<<>>` xref macro.
++
+[source,asciidoc]
+----
+<<title-heading>>
+----
+
+* To create an anchor with a custom URL caption example, specify the anchored ID and desired name separated by `,` without white space.
++
+[source,asciidoc]
+----
+<<title-heading,Title heading description that fits the context of your content>>
+----
++
+WARNING: Do not use the <<>> format with the verbatim heading or section description, such as
+<<Title heading>>.
+
+* To call an anchored ID from a different file, use the full file name and anchored ID separated by `#`,
+and specify the human-readable URL caption.
++
+[source,asciidoc]
+----
+xref:<other-file-name>.adoc#title-heading[Title heading]
+----
+
+
+* To refer to another file, use the xref macro with the full file name syntax.
+Specify the human-readable URL caption.
++
+[source,asciidoc]
+----
+xref:<name-of-the-file>.adoc[Human-readable label]
+----
+
 == Guidelines for good How-To guides
 
 - Don’t explain concepts; link to a related concept/explainer.

diff --git a/docs/src/main/asciidoc/_templates/template-reference.adoc b/docs/src/main/asciidoc/_templates/template-reference.adoc
@@ -32,6 +32,50 @@ include::{includes}/extension-status.adoc[]
 - xref:{doc-guides}/doc-concept.adoc#reference[Quarkus documentation content types: Reference guides]
 - xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]
 
+== Anchors for in-file and cross-file navigation
+
+* To create an anchored ID, use lower-case characters, Separate each word with `-` and enclose the ID in `[[]]` as in the example below.
++
+[source,asciidoc]
+----
+[[title-heading]]
+== Title heading
+----
+
+* To call an anchor created in the same file, insert the anchored ID in a `<<>>` xref macro.
++
+[source,asciidoc]
+----
+<<title-heading>>
+----
+
+* To create an anchor with a custom URL caption example, specify the anchored ID and desired name separated by `,` without white space.
++
+[source,asciidoc]
+----
+<<title-heading,Title heading description that fits the context of your content>>
+----
++
+WARNING: Do not use the <<>> format with the verbatim heading or section description, such as
+<<Title heading>>.
+
+* To call an anchored ID from a different file, use the full file name and anchored ID separated by `#`,
+and specify the human-readable URL caption.
++
+[source,asciidoc]
+----
+xref:<other-file-name>.adoc#title-heading[Title heading]
+----
+
+
+* To refer to another file, use the xref macro with the full file name syntax.
+Specify the human-readable URL caption.
++
+[source,asciidoc]
+----
+xref:<name-of-the-file>.adoc[Human-readable label]
+----
+
 == Guidelines for a good reference
 
 - Be consistent

diff --git a/docs/src/main/asciidoc/_templates/template-tutorial.adoc b/docs/src/main/asciidoc/_templates/template-tutorial.adoc
@@ -64,4 +64,48 @@ In closing, describe (and admire, in a mild way) what your learner has accomplis
 
 == References
 
-To help direct the reader to more information about the content topic, optionally add a *References* section to the end of the page and include `links` or `xrefs` to other related content resources.
+To help direct the reader to more information about the content topic, optionally add a *References* section to the end of the page and include `links` or `xrefs` to other related content resources.
+
+== Anchors for in-file and cross-file navigation
+
+* To create an anchored ID, use lower-case characters, Separate each word with `-` and enclose the ID in `[[]]` as in the example below.
++
+[source,asciidoc]
+----
+[[title-heading]]
+== Title heading
+----
+
+* To call an anchor created in the same file, insert the anchored ID in a `<<>>` xref macro.
++
+[source,asciidoc]
+----
+<<title-heading>>
+----
+
+* To create an anchor with a custom URL caption example, specify the anchored ID and desired name separated by `,` without white space.
++
+[source,asciidoc]
+----
+<<title-heading,Title heading description that fits the context of your content>>
+----
++
+WARNING: Do not use the <<>> format with the verbatim heading or section description, such as
+<<Title heading>>.
+
+* To call an anchored ID from a different file, use the full file name and anchored ID separated by `#`,
+and specify the human-readable URL caption.
++
+[source,asciidoc]
+----
+xref:<other-file-name>.adoc#title-heading[Title heading]
+----
+
+
+* To refer to another file, use the xref macro with the full file name syntax.
+Specify the human-readable URL caption.
++
+[source,asciidoc]
+----
+xref:<name-of-the-file>.adoc[Human-readable label]
+----
diff --git a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc
@@ -69,6 +69,66 @@ There must also be a line break before and after the abstract.
 
 For more information about the minimum header requirements, see xref:{doc-guides}/doc-reference.adoc#document-structure[Document structure] on the "Quarkus style and content guidelines" page.
 
+=== Anchors for in-file and cross-file navigation
+
+An anchor, also called an ID, can be defined almost anywhere in the document, including on a section title, discrete heading, paragraph, image, delimited block, inline phrase, etc.
+
+The callout functions for these anchors vary based on whether you call a local ID or the ID from another file, but the anchored ID creation remains the same.
+
+==== Creating anchored IDs
+
+To create an ID for a new file or a section to which you want to refer, insert the anchor ID as follows:
+
+* Use lower-case characters.
+* Separate each word with a dash character.
+* Enclose the ID in double square brackets.
+
+.Anchored ID creation example
+
+In this section, we will use an anchor created above the level-2 heading for demonstration purposes.
+
+[source,asciidoc]
+----
+[[title-heading]]
+== Title heading
+----
+
+==== Calling an anchored ID in the same file
+
+To call an anchor created in the same file, insert the anchored ID in a `<<>>` xref macro.
+
+.Inter-document anchored ID call example
+[source,asciidoc]
+----
+<<title-heading>>
+----
+
+This macro creates an URL with a name automatically sourced from the anchored heading, section, or table.
+
+WARNING: Don't use the <<>> format with the verbatim heading or section description, such as
+<<Title heading>>.
+
+When you want to specify a non-default caption for your URL, specify the anchored ID and desired name separated by `,` without white space.
+
+.Anchor with a custom URL caption example
+[source,asciidoc]
+----
+<<title-heading,Title heading description that fits the context of your content>>
+----
+
+==== Calling an anchored ID from a different file
+
+To call an anchor created in a different file, insert the anchor to an `xref` macro and specify the full name of the hosting file and the desired anchored ID.
+
+.Cross-document anchored ID call example
+[source,asciidoc]
+----
+xref:<other-file-name>.adoc#title-heading[Title heading]
+----
+
+Thus, use the `xref:<name-of-the-file>.adoc[Human-readable label]` syntax to refer to another file.
+
+
 == Retire and redirect an existing Quarkus AsciiDoc source file
 
 As content evolves, you might want to restructure an existing piece of Quarkus content into one or more content types and retire the existing AsciiDoc source file.

diff --git a/docs/src/main/asciidoc/doc-reference.adoc b/docs/src/main/asciidoc/doc-reference.adoc
@@ -121,7 +121,8 @@ Quarkus documentation uses a flat hierarchy.
 The bulk of the file name should be some representation of its title.
 Use all lowercase letters, separate words with hyphens, and avoid symbols and special characters.
 
-Prefix:: Use a common prefix to group related documents. Documents related to writing and contributing to Quarkus docs share the `doc-` prefix, for example.
+Prefix:: Use a common prefix to group-related documents.
+Documents related to writing and contributing to Quarkus docs share the `doc-` prefix, for example.
 
 Suffix:: The file name should reflect the document type:
 
@@ -159,7 +160,8 @@ Minimally, each document should define and id and a title, and include common at
 The value of this attribute is used in tiles or other descriptions on the website and is not required in newer diataxis-styled docs, as outlined in <<abstracts-preamble>>. 
 If not present, the first sentence of the abstract is automatically used to generate the tile summary. 
 
-IMPORTANT: Take care with whitespace when working with document-scoped attributes. The document header ends with the first blank line. 
+IMPORTANT: Take care with whitespace when working with document-scoped attributes.
+The document header ends with the first blank line.
 
 [[abstracts-preamble]]
 === Abstracts (preamble)
@@ -194,7 +196,7 @@ Start a new line at the end of each sentence, and split sentences themselves at
 
 === Using sections
 
-Section titles should be written in sentence case, rather than title case.
+Section titles should be written in sentence case rather than title case.
 
 All documents should start with a Title (a `= Level 0` heading), and should 
 be broken into subsections where appropriate
@@ -216,13 +218,13 @@ See xref:{doc-guides}/doc-concept.adoc[Quarkus documentation content types] for
 
 === Links
 
-In general, prefer https://docs.asciidoctor.org/asciidoc/latest/macros/url-macro/[url macros] to bare or automatic links.
+In general, prefer link:https://docs.asciidoctor.org/asciidoc/latest/macros/url-macro/[url macros] to bare or automatic links.
 Provide human-readable text for the link, especially if it is included in the middle of other text.
 
 .A URL Macro link with attributes
 [NOTE]
 =====
-The URL macro also supports https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro-ref/[additional attributes] that may be relevant, like opening a link in a different window.
+The URL macro also supports link:https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro-ref/[additional attributes] that may be relevant, like opening a link in a different window.
 
 [source,asciidoc]
 ----
@@ -258,6 +260,66 @@ xref:{doc-guides}/doc-concept.adoc[Quarkus Documentation concepts] <1>
 ----
 <1> The cross-reference starts with `xref:`, uses a cross-reference source attribute(`\{doc-guides}`), and provides a readable description: `[Quarkus Documentation concepts]`.
 
+=== Anchors for in-file and cross-file navigation
+
+An anchor, also called an ID, can be defined almost anywhere in the document, including on a section title, discrete heading, paragraph, image, delimited block, inline phrase, etc.
+
+The callout functions for these anchors vary based on whether you call a local ID or the ID from another file, but the anchored ID creation remains the same.
+
+==== Creating anchored IDs
+
+To create an ID for a new file or a section to which you want to refer, insert the anchor ID as follows:
+
+* Use lower-case characters.
+* Separate each word with a dash character.
+* Enclose the ID in double square brackets.
+
+.Anchored ID creation example
+
+In this section, we will use an anchor created above the level-2 heading for demonstration purposes.
+
+[source,asciidoc]
+----
+[[title-heading]]
+== Title heading
+----
+
+==== Calling an anchored ID in the same file
+
+To call an anchor created in the same file, insert the anchored ID in a `<<>>` xref macro.
+
+.Inter-document anchored ID call example
+[source,asciidoc]
+----
+<<title-heading>>
+----
+
+This macro creates an URL with a name automatically sourced from the anchored heading, section, or table.
+
+WARNING: Do not use the <<>> format with the verbatim heading or section description, such as
+<<Title heading>>.
+
+When you want to specify a non-default caption for your URL, specify the anchored ID and desired name separated by `,` without white space.
+
+.Anchor with a custom URL caption example
+[source,asciidoc]
+----
+<<title-heading,Title heading description that fits the context of your content>>
+----
+
+==== Calling an anchored ID from a different file
+
+To call an anchor created in a different file, insert the anchor to an `xref` macro and specify the full name of the hosting file and the desired anchored ID.
+
+.Cross-document anchored ID call example
+[source,asciidoc]
+----
+xref:<other-file-name>.adoc#title-heading[Title heading]
+----
+
+Thus, use the `xref:<name-of-the-file>.adoc[Human-readable label]` syntax to refer to another file.
+
+
 === Reference source code 
 
 There are many ways to include source code and examples in documentation.