From 4f7c5fa92b2df16848b89b3faf2170cc804f32f2 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 fb5ad1ced4012..05ea9239877dd 100644 --- a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc +++ b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc @@ -69,6 +69,68 @@ 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-howto]] +=== Cross-reference in-file and cross-file content by using anchors + +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. + == 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 index 907359f0952c6..7c2bf0a67e506 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.