Doc reference edits

Signed-off-by: Michal Maléř <mmaler@redhat.com> Docummenting ways for in-file and cross-file navigation Signed-off-by: Michal Maléř <mmaler@redhat.com> Review Signed-off-by: Michal Maléř <mmaler@redhat.com> Review and fixes Signed-off-by: Michal Maléř <mmaler@redhat.com> Review and fixes Signed-off-by: Michal Maléř <mmaler@redhat.com> Review and fixes Signed-off-by: Michal Maléř <mmaler@redhat.com> Review and fixes Signed-off-by: Michal Maléř <mmaler@redhat.com> Review and fixes Signed-off-by: Michal Maléř <mmaler@redhat.com> Apply suggestions from code review Co-authored-by: Erin Schnabel <ebullientworks@gmail.com> Apply suggestions from code review Co-authored-by: Erin Schnabel <ebullientworks@gmail.com>
quarkusio · May 16, 2023 · f39a50c · f39a50c
1 parent 6bfb493
commit f39a50c
Show file tree

Hide file tree

Showing 7 changed files with 153 additions and 11 deletions.
diff --git a/docs/src/main/asciidoc/_includes/devtools/create-cli.adoc b/docs/src/main/asciidoc/_includes/devtools/create-cli.adoc
@@ -86,4 +86,4 @@ endif::[]
 ----
 
 To create a Gradle project, add the `-DbuildTool=gradle` or `-DbuildTool=gradle-kotlin-dsl` option.
-****
+****
diff --git a/docs/src/main/asciidoc/_templates/template-concept.adoc b/docs/src/main/asciidoc/_templates/template-concept.adoc
@@ -32,13 +32,22 @@ 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]
 
+=== Create cross-references
+
+To create anchors for in-file and cross-file navigation, see the following detailed instructions in the Quarkus style and content guidelines.
+
+* xref:{doc-guides}doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors]
+
+* xref:{doc-guides}doc-reference.adoc#cross-references[Cross-references]
+
+
 == Guidelines for a good Concept doc
 
 Explanation/Concept documents should do things that the other parts of the documentation do not.
 
-- Make connections to other things, even to things outside the immediate topic, if that helps explain the concept.
-- Provide background and context in your explanation: explain why things are so - design decisions, historical reasons, technical constraints - draw implications, mention specific examples.
-- Consider alternatives, counter-examples or multiple different approaches to the same question.
+* Make connections to other things, even to something outside the immediate topic, if that helps explain the concept.
+* Provide background and context in your explanation: explain why things are so - design decisions, historical reasons, technical constraints - draw implications, mention specific examples.
+* Consider alternatives, counter-examples, or multiple different approaches to the same question.
 
 == Language tips:
 

diff --git a/docs/src/main/asciidoc/_templates/template-howto.adoc b/docs/src/main/asciidoc/_templates/template-howto.adoc
@@ -36,6 +36,14 @@ 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]
 
+=== Create cross-references
+
+To create anchors for in-file and cross-file navigation, see the following detailed instructions in the Quarkus style and content guidelines.
+
+* xref:{doc-guides}doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors]
+
+* xref:{doc-guides}doc-reference.adoc#cross-references[Cross-references]
+
 == 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,14 @@ 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]
 
+=== Create cross-references
+
+To create anchors for in-file and cross-file navigation, see the following detailed instructions in the Quarkus style and content guidelines.
+
+* xref:{doc-guides}doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors]
+
+* xref:{doc-guides}doc-reference.adoc#cross-references[Cross-references]
+
 == 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,12 @@ 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.
+
+=== Create cross-references
+
+To create anchors for in-file and cross-file navigation, see the following detailed instructions in the Quarkus style and content guidelines.
+
+* xref:{doc-guides}doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors]
+
+* xref:{doc-guides}doc-reference.adoc#cross-references[Cross-references]
diff --git a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc
@@ -149,6 +149,68 @@ Where:
 
 |===
 
+[[anchors-howto]]
+== Use anchors to cross-reference in-file and cross-file content
+
+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.
+
+=== Create an anchored ID
+
+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
+----
+
+=== Call 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>>
+----
+
+=== Call 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]
+----
+
+Breaking this example apart, we are using the `xref` macro to refer to another file (`xref:<name-of-the-file>.adoc[Human-readable label]`) and inserting the anchor ID for the target section (`#title-heading`) just after the file name.
+
+See the xref:doc-reference.adoc#cross-references[Cross-references] section for path attributes that should be used in cross-document references.
+
 == Preview and build Quarkus documentation
 
 Before you submit a pull request, preview the HTML output of your AsciiDoc source by using one of the following build methods:

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,22 +218,23 @@ 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]
 ----
 https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference,window=_blank,opts=nofollow]
 ----
 
-The above source produces this link: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference,window=_blank,opts=nofollow].
+The above source produces this link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference,window=_blank,opts=nofollow].
 =====
 
+[[cross-references]]
 === Cross-references
 
 Quarkus documentation is built from source in a few different environments.
@@ -258,6 +261,50 @@ 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-reference]]
+==== 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 and always specify the human-readable URL caption.
++
+[source,asciidoc]
+----
+xref:<name-of-the-file>.adoc[Human-readable label]
+----
+For more details about anchored IDs, see the xref:doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors] section.
+
 === Reference source code 
 
 There are many ways to include source code and examples in documentation.