diff --git a/docs/src/main/asciidoc/_attributes-local.adoc b/docs/src/main/asciidoc/_attributes-local.adoc index baa44e6595526..63916a17c1c0e 100644 --- a/docs/src/main/asciidoc/_attributes-local.adoc +++ b/docs/src/main/asciidoc/_attributes-local.adoc @@ -7,7 +7,6 @@ :icons: font :generated-dir: ../../../../target/asciidoc/generated :code-examples: {generated-dir}/examples -:doc-guides: ./ :doc-examples: ./_examples :imagesdir: ./images :includes: ./_includes diff --git a/docs/src/main/asciidoc/_templates/_attributes.adoc b/docs/src/main/asciidoc/_templates/_attributes.adoc index 5f8fbca566769..566e7889f794c 100644 --- a/docs/src/main/asciidoc/_templates/_attributes.adoc +++ b/docs/src/main/asciidoc/_templates/_attributes.adoc @@ -4,7 +4,6 @@ :idseparator: - :icons: font :code-examples: ../../../../../target/asciidoc/generated/examples -:doc-guides: .. :doc-examples: ../_examples :imagesdir: ../images :includes: ../includes \ 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 fd3ff6174d4a6..b91006b491ea6 100644 --- a/docs/src/main/asciidoc/_templates/template-concept.adoc +++ b/docs/src/main/asciidoc/_templates/template-concept.adoc @@ -4,7 +4,7 @@ and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// //// -TODO: +TODO: - Title: https://quarkus.io/guides/doc-reference#titles-headings - Use the file name as the ID - Choose appropriate categories: https://quarkus.io/guides/doc-reference#categories @@ -16,7 +16,7 @@ include::_attributes.adoc[] :categories: ... //// :extension-status: preview -TODO: uncomment the above for experimental or tech-preview content. +TODO: uncomment the above for experimental or tech-preview content. The document header ends at the first blank line. Do not remove the blank line between the header and the abstract summary. //// @@ -30,16 +30,16 @@ include::{includes}/extension-status.adoc[] == Create additional sections -- xref:{doc-guides}/doc-concept.adoc#concept[Quarkus documentation content types: Concept guides] -- xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] +- xref:../doc-concept.adoc#concept[Quarkus documentation content types: Concept guides] +- xref:../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-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] +* xref:../doc-reference.adoc#cross-references[Cross-references] == Guidelines for a good Concept doc diff --git a/docs/src/main/asciidoc/_templates/template-howto.adoc b/docs/src/main/asciidoc/_templates/template-howto.adoc index 8311c5e8c13bb..385fa018a4f11 100644 --- a/docs/src/main/asciidoc/_templates/template-howto.adoc +++ b/docs/src/main/asciidoc/_templates/template-howto.adoc @@ -45,17 +45,17 @@ Your user will also be in the middle of something: define the starting-point tha == Resources -- xref:{doc-guides}/doc-create-howto-tutorial.adoc[Tutorial: Create a How-To] -- 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] +- xref:../doc-create-howto-tutorial.adoc[Tutorial: Create a How-To] +- xref:../doc-concept.adoc#howto-guide[Quarkus documentation content types: How-to guides] +- xref:../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-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] +* xref:../doc-reference.adoc#cross-references[Cross-references] == Guidelines for good How-To guides diff --git a/docs/src/main/asciidoc/_templates/template-reference.adoc b/docs/src/main/asciidoc/_templates/template-reference.adoc index c5dd979cf85f4..745e7b24e965b 100644 --- a/docs/src/main/asciidoc/_templates/template-reference.adoc +++ b/docs/src/main/asciidoc/_templates/template-reference.adoc @@ -4,7 +4,7 @@ and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// //// -TODO: +TODO: - Title: https://quarkus.io/guides/doc-reference#titles-headings - Use the file name as the ID - Choose appropriate categories: https://quarkus.io/guides/doc-reference#categories @@ -16,7 +16,7 @@ include::_attributes.adoc[] :categories: ... //// :extension-status: preview -TODO: uncomment the above for experimental or tech-preview content. +TODO: uncomment the above for experimental or tech-preview content. The document header ends at the first blank line. Do not remove the blank line between the header and the abstract summary. //// @@ -30,16 +30,16 @@ include::{includes}/extension-status.adoc[] == Add additional sections -- xref:{doc-guides}/doc-concept.adoc#reference[Quarkus documentation content types: Reference guides] -- xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] +- xref:../doc-concept.adoc#reference[Quarkus documentation content types: Reference guides] +- xref:../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-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] +* xref:../doc-reference.adoc#cross-references[Cross-references] == Guidelines for a good reference diff --git a/docs/src/main/asciidoc/_templates/template-tutorial.adoc b/docs/src/main/asciidoc/_templates/template-tutorial.adoc index c52b16a72e7bc..04c0337596590 100644 --- a/docs/src/main/asciidoc/_templates/template-tutorial.adoc +++ b/docs/src/main/asciidoc/_templates/template-tutorial.adoc @@ -4,7 +4,7 @@ and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// //// -TODO: +TODO: - Title: https://quarkus.io/guides/doc-reference#titles-headings - Use the file name as the ID - Choose appropriate categories: https://quarkus.io/guides/doc-reference#categories @@ -16,7 +16,7 @@ include::_attributes.adoc[] :categories: ... //// :extension-status: preview -TODO: uncomment the above for experimental or tech-preview content. +TODO: uncomment the above for experimental or tech-preview content. The document header ends at the first blank line. Do not remove the blank line between the header and the abstract summary. //// @@ -43,9 +43,9 @@ This file offers a few different variables that can be used to tweak what is sho :sectnumlevels: 3 == Outline steps -- xref:{doc-guides}/doc-create-tutorial.adoc[Tutorial: Create a tutorial] -- xref:{doc-guides}/doc-concept.adoc#tutorial[Quarkus documentation content types: Tutorials] -- xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] +- xref:../doc-create-tutorial.adoc[Tutorial: Create a tutorial] +- xref:../doc-concept.adoc#tutorial[Quarkus documentation content types: Tutorials] +- xref:../doc-reference.adoc[Quarkus style and content guidelines] Each step should conclude with a comprehensible/observable result. @@ -71,6 +71,6 @@ To help direct the reader to more information about the content topic, optionall 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-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 +* xref:../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 8c522b2cb95f6..9500f2b1b02ee 100644 --- a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc +++ b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc @@ -19,8 +19,8 @@ Quarkus docs use link:https://asciidoc.org/[AsciiDoc] markup. * You have an editor or IDE that provides syntax highlighting and previews for AsciiDoc, either natively or with a plugin. * You have reviewed the following Quarkus contributor resources: ** The link:https://github.com/quarkusio/quarkus/blob/main/CONTRIBUTING.md#documentation[Documentation] section of the Quarkus "Contributing" guide. -** The xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for the required syntax, preferred style, and other conventions. -** The xref:{doc-guides}/doc-concept.adoc[Quarkus documentation content types]. +** The xref:doc-reference.adoc[Quarkus style and content guidelines] for the required syntax, preferred style, and other conventions. +** The xref:doc-concept.adoc[Quarkus documentation content types]. * You have the https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc syntax reference] nearby. == Locate the source files for Quarkus docs @@ -38,7 +38,7 @@ To ensure that your content shows up correctly on the link:https://quarkus.io/gu . Decide on a xref:doc-concept.adoc[Diataxis] content type that best fits the content that you are contributing. + -TIP: To help you decide, see the content type descriptions in xref:{doc-guides}/doc-reference.adoc#titles-and-headings[Titles and headings] on the "About Quarkus documentation" page. +TIP: To help you decide, see the content type descriptions in xref:doc-reference.adoc#titles-and-headings[Titles and headings] on the "About Quarkus documentation" page. . Go to the `src/main/asciidoc/_templates` directory, and make a copy of the relevant template for the content type you have chosen. Be sure to: ** Use the filename syntax of`--.adoc`. For example, `security-basic-authentication.adoc`. @@ -58,10 +58,10 @@ include::_attributes.adoc[] <3> <6> ---- <1> Set the `id` value to be the same as the file name but without the extension. -<2> For information about how to create a good title for each content type, see xref:{doc-guides}/doc-reference.adoc#titles-and-headings[Titles and headings] on the "Quarkus style and content guidelines" page. +<2> For information about how to create a good title for each content type, see xref:doc-reference.adoc#titles-and-headings[Titles and headings] on the "Quarkus style and content guidelines" page. <3> The `_attributes.adoc` include is required to ensure that attributes get resolved and the table of contents is generated. <4> Specify the diataxis type: `concept`, `howto`, `reference`, or `tutorial`. -<5> Set at least one category to ensure that the content is findable on the link:https://quarkus.io/guides/[Quarkus documentation home page]. For a list of Quarkus categories, see xref:{doc-guides}/doc-reference.adoc#document-attributes-and-variables[Document attributes and variables] on the "Quarkus style and content guidelines" page. +<5> Set at least one category to ensure that the content is findable on the link:https://quarkus.io/guides/[Quarkus documentation home page]. For a list of Quarkus categories, see xref:doc-reference.adoc#document-attributes-and-variables[Document attributes and variables] on the "Quarkus style and content guidelines" page. <6> Insert a blank line after all document attributes and before the abstract. + [IMPORTANT] @@ -77,7 +77,7 @@ The first sentence of the abstract must explain the value and some benefit of th 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. +For more information about the minimum header requirements, see xref:doc-reference.adoc#document-structure[Document structure] on the "Quarkus style and content guidelines" page. [id="add-prerequisites"] == Add a prerequisites section diff --git a/docs/src/main/asciidoc/doc-reference.adoc b/docs/src/main/asciidoc/doc-reference.adoc index 9e6329705d137..203ed563b0f95 100644 --- a/docs/src/main/asciidoc/doc-reference.adoc +++ b/docs/src/main/asciidoc/doc-reference.adoc @@ -227,7 +227,7 @@ If you end up with deeply nested sections, think about the following: For example, if this is a reference, should some of this content be moved to a concept doc or how-to guide instead? - Can the content be reorganized to make it simpler to consume? -See xref:{doc-guides}/doc-concept.adoc[Quarkus documentation content types] for more information about content types and organization. +See xref:doc-concept.adoc[Quarkus documentation content types] for more information about content types and organization. ==== == Links @@ -264,7 +264,6 @@ We use attributes in our cross-references to ensure our docs can be built across |Attribute|Description |\{code-examples}|Relative path to directory containing collected example source files |\{doc-examples}|Relative path to source examples for documentation guides -|\{doc-guides}|Relative path to documentation adoc files |\{generated-dir}|Relative path to generated configuration `*.adoc` files |\{imagesdir}|Relative path to directory containing images |\{includes}|Relative path to directory containing partial/reusable content @@ -275,9 +274,9 @@ When cross-referencing content, always use the inter-document `xref:` syntax and .Cross-reference example [source,asciidoc] ---- -xref:{doc-guides}/doc-concept.adoc[Quarkus Documentation concepts] <1> +xref: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]`. +<1> The cross-reference starts with `xref:`, and provides a readable description: `[Quarkus Documentation concepts]`. [[anchors-reference]] === Anchors for in-file and cross-file navigation