diff --git a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc index 363274ea3fb46..3880fd7337a98 100644 --- a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc +++ b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc @@ -54,6 +54,18 @@ include::_attributes.adoc[] <3> <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, the table of contents is generated, and content renders in the website portal. <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. ++ +[IMPORTANT] +==== +Ensure there are no line breaks in the header section until after `:categories:` line. +==== ++ +. Add an abstract to describe the purpose of the guide. +[IMPORTANT] +==== +The first sentence of the abstract must explain the value and some benefit of the content in less than 27 words because this automatically displays on the link:https://quarkus.io/guides/[Quarkus guides homepage]. +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. @@ -75,8 +87,8 @@ newUrl: /guides/ // <2> --- + Where: -<1> Is the name of the original AsciiDoc source file that you are retiring. -<2> Is the name of the AsciiDoc source file that you want to redirect to. +<1> Is the name of the original AsciiDoc source file that you are retiring, without the `.adoc` file extension. +<2> Is the name of the AsciiDoc source file that you want to redirect to, without the `.adoc` file extension. .Example diff --git a/docs/src/main/asciidoc/doc-reference.adoc b/docs/src/main/asciidoc/doc-reference.adoc index 2dbebf6e02ed5..d71bf0fd59972 100644 --- a/docs/src/main/asciidoc/doc-reference.adoc +++ b/docs/src/main/asciidoc/doc-reference.adoc @@ -149,29 +149,40 @@ Minimally, each document should define and id and a title, and include common at <3> Include common document attributes. <4> Specify the relevant <> (comma separated). -==== Other common document attributes: +[[doc-header-optional]] +==== Other common document header attributes `:extension-status: preview`:: Use this attribute to flag special types of content. Valid values: `experimental`, `preview`, `stable` (not usually used), and `deprecated`. `:summary: `:: Use the summary to provide a concise (26 words or less) description of the document. -This attribute will be used in tiles or other descriptions on the website. If not present, the contents of the <> will be used instead. +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 <>. +If not present, the first sentence of the abstract is automatically used to generate the tile summary. -NOTE: 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) -Add a short description that helps your audience to quickly find and understand the purpose and intent of the page. +The first paragraph in the main body is treated as the abstract, also referred to as the preamble. +Add a short description that helps your audience quickly find and understand the purpose and intent of the page. +The first sentence of the abstract provides a summary and gets automatically added to the tile on the link:https://quarkus.io/guides/[Quarkus guides homepage]. Try to write the abstract by using the following guidelines: * *User oriented:* Contains terms and keywords that are familiar to users. -* *Concise:* Avoids self-referential expressions and filler words, for example, "This document..", "This tutorial..", or "The following.." +* *Concise:* Avoids self-referential expressions and filler words, for example: +** "This document.." +** "This tutorial..." +** "The following..." * *Brief:* Is no more than three sentences long. [IMPORTANT] ==== -The first sentence of the abstract must explain the value and some benefit of the content in less than 27 words because this automatically displays on the link:https://quarkus.io/guides/[Quarkus guides homepage]. +Ensure that the first sentence explains the value and some benefits of the content in 26 words or less. ==== +If the first sentence is too long or can not be simplified to fit on the website tile, you can define a ``:summary:`` attribute in the document header attributes to serve that purpose. +For more information, see <>. + === Semantic line breaks :semantic-line-breaks: footnote:smbl[Rhodes, B. Semantic Linefeeds. https://rhodesmill.org/brandon/2012/one-sentence-per-line/]