Determine document type from attributes

Author: ebullient

docs/pom.xml

@@ -3003,7 +3003,7 @@
                     </execution>
                     <execution>
                         <id>generate-doc-manifests</id>
-                        <phase>prepare-package</phase>
+                        <phase>package</phase>
                         <goals>
                             <goal>java</goal>
                         </goals>

docs/src/main/asciidoc/_examples/acme-serve-http-requests-tutorial.adoctxt

@@ -6,12 +6,13 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="acme-serve-http-requests-tutorial"]
 = Serve Http requests using the Acme extension
 include::_attributes.adoc[]
+:diataxis-type: tutorial
 :categories: web
 :extension-status: experimental
 
-In this tutorial, we will create an application that uses unique annotations from the experimental acme extension to define two endpoints:
-a simple Http endpoint and an endpoint that emits Server-Sent Events (SSE).
-We will also use Quarkus dev mode for iterative development and test.
+Create an application that uses unique annotations from the experimental acme extension to define two endpoints:
+a simple HTTP endpoint and an endpoint that emits server-sent events (SSE).
+We will also use Quarkus dev mode for iterative development and testing.
 
 include::{includes}/extension-status.adoc[]
 

docs/src/main/asciidoc/_templates/template-concept.adoc

@@ -4,14 +4,15 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 ////
-TODO: xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for details
-- Title should have an implied "Understanding..." in front. 
-- ID should end with '-concept' (using the filename works)
-- choose appropriate categories
+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
 ////
-[id="...-concept"]
+[id="..."]
 = Title using sentence capitalization
 include::_attributes.adoc[]
+:diataxis-type: concept
 :categories: ...
 ////
 :extension-status: preview

docs/src/main/asciidoc/_templates/template-howto.adoc

@@ -4,14 +4,15 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 ////
-TODO: See xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for details
-- Title should have an implied "How to..." in front.
-- ID should end with '-howto' (using the filename works)
-- choose appropriate categories
+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
 ////
-[id="...-howto"]
+[id="..."]
 = Title using sentence capitalization
 include::_attributes.adoc[]
+:diataxis-type: howto
 :categories: ...
 ////
 :extension-status: preview

docs/src/main/asciidoc/_templates/template-reference.adoc

@@ -4,14 +4,15 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 ////
-TODO: See xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for details
-- Title should have an implied "About..." in front. 
-- ID should end with '-reference' (using the filename works)
-- choose appropriate categories
+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
 ////
-[id="...-reference"]
+[id="..."]
 = Title using sentence capitalization
 include::_attributes.adoc[]
+:diataxis-type: reference
 :categories: ...
 ////
 :extension-status: preview

docs/src/main/asciidoc/_templates/template-tutorial.adoc

@@ -4,14 +4,15 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 ////
-TODO: See xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]for details
-- Finish a sentence like: "Create a ...", "How to ..." 
-- ID should end with '-tutorial' (using the filename works)
-- choose appropriate categories 
+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
 ////
-[id="...-tutorial"]
+[id="..."]
 = Title using sentence capitalization
 include::_attributes.adoc[]
+:diataxis-type: tutorial
 :categories: ...
 ////
 :extension-status: preview

docs/src/main/asciidoc/doc-concept.adoc

@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="doc-concept"]
 = Quarkus documentation content types
 include::_attributes.adoc[]
+:diataxis-type: concept
 :categories: contributing
 :fn-diataxis: footnote:diataxis[Procida, D. Diátaxis documentation framework. https://diataxis.fr/]
 

docs/src/main/asciidoc/doc-contribute-docs-howto.adoc

@@ -5,6 +5,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="doc-contribute-howto"]
 = Contribute to Quarkus documentation
 include::_attributes.adoc[]
+:diataxis-type: howto
 :categories: contributing
 :fn-diataxis: footnote:diataxis[Procida, D. Diátaxis documentation framework. https://diataxis.fr/]
 
@@ -39,28 +40,32 @@ To ensure that your content shows up correctly on the link:https://quarkus.io/gu
 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.
 
 . 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`<category>-<titlekeyword>-<titlekeyword>-<content-type>.adoc`. For example, `security-basic-authentication-tutorial.adoc`.
+** Use the filename syntax of`<category>-<titlekeyword>-<titlekeyword>.adoc`. For example, `security-basic-authentication.adoc`.
+** Include the diataxis type (concept, howto, reference, tutorial) in the file name if it makes sense to do so.
+For example, `telemetry-micrometer.adoc` is a reference, and `telemetry-micrometer-tutorial.adoc` is a tutorial.
 ** Save the file to the `docs/src/main/asciidoc` folder in the `quarkus` repository.
 
 . Set the minimum required header information to ensure that the content renders correctly in the website portal and on the documentation home page, as outlined in the following example:
 +
 [source,asciidoc]
 ----
-[id="security-basic-authentication-howto"] <1>
+[id="security-basic-authentication"] <1>
 = Secure a Quarkus application with basic authentication <2>
 include::_attributes.adoc[] <3>
-:categories: security,web <4>
-<5>
+:diataxis-type: howto <4>
+:categories: security,web <5>
+<6>
 ----
-<1> Set the `id` value to be the same as the file name but without the extension. You can shorten this if the file name is too long.
+<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.
 <3> The `_attributes.adoc` include is required to ensure that attributes get resolved and the table of contents is generated.
-<4> 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> Insert a blank line before the abstract.
+<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.
+<6> Insert a blank line after all document attributes and before the abstract.
 +
 [IMPORTANT]
 ====
-Ensure there are no line breaks in the header section until after `:categories:` line.
+Ensure there are no blank lines between the document id and title, the attribute include (`include::_attributes.adoc[]`) and the declaration of other document attributes(`:attribute:`).
 ====
 
 . Add an abstract that describes the purpose of the guide.

docs/src/main/asciidoc/doc-create-tutorial.adoc

@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="doc-create-tutorial"]
 = Creating a tutorial
 include::_attributes.adoc[]
+:diataxis-type: tutorial
 :categories: contributing
 
 Create a new tutorial that guides users through creating, running, and testing a Quarkus application that uses annotations from an imaginary extension.
@@ -29,7 +30,8 @@ For this example, we will use `acme-serve-http-requests-tutorial.adoc`:
 
 - `acme-` will group this guide with other resources related to the acme extension
 - `serve-http-requests` is a derivative of the document title
-- `-tutorial.adoc` will indicate that this document is a tutorial
+- `-tutorial` will indicate that this document is a tutorial (optional)
+- `.adoc` to indicate this is an asciidoc file
 
 == Copy the tutorial template
 
@@ -46,7 +48,7 @@ include::_attributes.adoc[] // <3>
 :extension-status: experimental // <5>
 ----
 
-<1> Specify a unique id for the section in lower-kebab-case.
+<1> Use the file name as a unique id for the section.
 <2> Add the title as a top-level heading.
 <3> Include additional attributes that help define consistent formatting and provide source portability.
 <4> Specify the `web` category, as our imaginary extension works with Http requests.

docs/src/main/asciidoc/doc-reference.adoc

@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="doc-reference"]
 = Quarkus style and content guidelines
 include::_attributes.adoc[]
+:diataxis-type: reference
 :categories: contributing
 
 Guidelines are provided to help you to contribute clear and consistent content that is also sourced in the required diataxis structure and composition of Quarkus documentation.
@@ -132,13 +133,12 @@ Use all lowercase letters, separate words with hyphens, and avoid symbols and sp
 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:
-
-- Concept documents should end in `-concept.adoc`
-- How-to guides should end in `-howto.adoc`
-- References should end in `-reference.adoc`
-- Tutorials should end in `-tutorial.adoc`
+Suffix:: Use a suffix that reflects the document type (optional):
 
+- `-concept.adoc` for concept documents
+- `-howto.adoc` for how-to guides
+- `-reference.adoc` for references 
+- `-tutorial.adoc` for tutorials
 
 [[doc-structure]]
 == Document structure
@@ -156,13 +156,15 @@ Minimally, each document should define and id and a title, and include common at
 [id="doc-reference"] // <1>
 = Quarkus style and content guidelines // <2>
 \include::_attributes.adoc[] // <3>
-:categories: contributing // <4>
+:diataxis-type: {type} // <4>
+:categories: contributing // <5>
 ----
 
 <1> Use the filename as the ID for the document.
 <2> Define the document title following guidance in <<titles-headings>>.
 <3> Include common document attributes.
-<4> Specify the relevant <<categories>> (comma separated).
+<4> Specify the diataxis type: `concept`, `howto`, `reference`, or `tutorial`.
+<5> Specify the relevant <<categories>> (comma separated).
 
 [[doc-header-optional]]
 ==== Other common document header attributes