From 0a428ea562100ecf9a729c2840502ff9797f26ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20Mal=C3=A9=C5=99?= Date: Wed, 22 Mar 2023 14:08:02 +0100 Subject: [PATCH] Doc reference edits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michal Maléř Docummenting ways for in-file and cross-file navigation Signed-off-by: Michal Maléř Review Signed-off-by: Michal Maléř Review and fixes Signed-off-by: Michal Maléř Review and fixes Signed-off-by: Michal Maléř Review and fixes Signed-off-by: Michal Maléř Review and fixes Signed-off-by: Michal Maléř Review and fixes Signed-off-by: Michal Maléř Apply suggestions from code review Co-authored-by: Erin Schnabel Apply suggestions from code review Co-authored-by: Erin Schnabel --- .../_includes/devtools/create-cli.adoc | 2 +- .../asciidoc/_templates/template-concept.adoc | 15 ++++- .../asciidoc/_templates/template-howto.adoc | 8 +++ .../_templates/template-reference.adoc | 8 +++ .../_templates/template-tutorial.adoc | 10 ++- .../asciidoc/doc-contribute-docs-howto.adoc | 62 +++++++++++++++++++ docs/src/main/asciidoc/doc-reference.adoc | 59 ++++++++++++++++-- 7 files changed, 153 insertions(+), 11 deletions(-) diff --git a/docs/src/main/asciidoc/_includes/devtools/create-cli.adoc b/docs/src/main/asciidoc/_includes/devtools/create-cli.adoc index 932184d383594..111abbc49b87f 100644 --- 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. -**** +**** \ No newline at end of file diff --git a/docs/src/main/asciidoc/_templates/template-concept.adoc b/docs/src/main/asciidoc/_templates/template-concept.adoc index 5d74926d19b59..836f75798347d 100644 --- 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 index a113412c9ac65..d0ebb6ccccb50 100644 --- 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 index 36f8a8f299f1c..ae2ecf969aef5 100644 --- 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 index 53b4b8ee900c4..279c79e7c56ed 100644 --- 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. \ No newline at end of file +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] \ No newline at end of file diff --git a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc index 43e8aedd59414..942e7d8fcadc7 100644 --- 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] +---- +<> +---- + +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 +`\<>`. + +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 index 0c8774698d302..06ba0bbb3d8f9 100644 --- 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.