Quarkus style and content guidelines

[id="doc-reference"] (1)
= Quarkus style and content guidelines (2)
// Common attributes.
// --> No blank lines (it ends the document header)
:project-name: Quarkus
:quarkus-version: ${project.version}
:quarkus-platform-groupid: io.quarkus.platform
// .
:maven-version: ${proposed-maven-version}
:graalvm-version: ${graal-community.version-for-documentation}
:graalvm-docs-version: ${graal-community.tag-for-documentation}
:graalvm-flavor: ${graal-community.image-tag-for-documentation}
:mandrel-flavor: ${mandrel.image-tag-for-documentation}
:surefire-version: ${version.surefire.plugin}
:gradle-version: ${gradle-wrapper.version}
:elasticsearch-version: ${elasticsearch-server.version}
:elasticsearch-image: ${elasticsearch.image}
:opensearch-image: ${opensearch.image}
:infinispan-version: ${infinispan.version}
:infinispan-protostream-version: ${infinispan.protostream.version}
:logstash-image: ${logstash.image}
:kibana-image: ${kibana.image}
:keycloak-docker-image: ${keycloak.docker.image}
:jandex-version: ${jandex.version}
:jandex-gradle-plugin-version: ${jandex-gradle-plugin.version}
:kotlin-version: ${kotlin.version}
:grpc-version: ${grpc.version}
:protoc-version: ${protoc.version}
:gcf-invoker-version: ${gcf-invoker.version}
// Cannot simply use the name 'hibernate-*-version' here as it somehow gets
// overridden to the full version, at least when building locally.
:hibernate-orm-version-major-minor: ${hibernate-orm.majorVersion}.${hibernate-orm.minorVersion}
:hibernate-search-version-major-minor: ${hibernate-search.majorVersion}.${hibernate-search.minorVersion}
// .
:quarkus-home-url: ${quarkus-home-url}
:quarkus-org-url: https://github.com/quarkusio
:quarkus-site-getting-started: /get-started
:quarkus-writing-extensions-guide: /guides/writing-extensions
:quarkus-site-publications: /publications
:quarkus-base-url: ${quarkus-base-url}
:quarkus-clone-url: ${quarkus-base-url}.git
:quarkus-archive-url: ${quarkus-base-url}/archive/main.zip
:quarkus-blob-url: ${quarkus-base-url}/blob/main
:quarkus-tree-url: ${quarkus-base-url}/tree/main
:quarkus-issues-url: ${quarkus-base-url}/issues
:quarkus-images-url: https://github.com/quarkusio/quarkus-images/tree
:quarkus-chat-url: https://quarkusio.zulipchat.com
:quarkus-mailing-list-subscription-email: quarkus-dev+subscribe@googlegroups.com
:quarkus-mailing-list-index: https://groups.google.com/d/forum/quarkus-dev
:quickstarts-base-url: ${quickstarts-base-url}
:quickstarts-clone-url: ${quickstarts-base-url}.git
:quickstarts-archive-url: ${quickstarts-base-url}/archive/main.zip
:quickstarts-blob-url: ${quickstarts-base-url}/blob/main
:quickstarts-tree-url: ${quickstarts-base-url}/tree/main
// .
:hibernate-orm-docs-url: https://docs.jboss.org/hibernate/orm/{hibernate-orm-version-major-minor}/userguide/html_single/Hibernate_User_Guide.html
:hibernate-orm-dialect-docs-url: https://docs.jboss.org/hibernate/orm/{hibernate-orm-version-major-minor}/dialect/dialect.html
:hibernate-search-docs-url: https://docs.jboss.org/hibernate/search/{hibernate-search-version-major-minor}/reference/en-US/html_single/
// .
:amazon-services-guide: https://quarkiverse.github.io/quarkiverse-docs/quarkus-amazon-services/dev/index.html
:config-consul-guide: https://quarkiverse.github.io/quarkiverse-docs/quarkus-config-extensions/dev/consul.html
:hibernate-search-orm-elasticsearch-aws-guide: https://quarkiverse.github.io/quarkiverse-docs/quarkus-hibernate-search-extras/dev/index.html
:neo4j-guide: https://quarkiverse.github.io/quarkiverse-docs/quarkus-neo4j/dev/index.html
:vault-guide: https://quarkiverse.github.io/quarkiverse-docs/quarkus-vault/dev/index.html
:vault-datasource-guide: https://quarkiverse.github.io/quarkiverse-docs/quarkus-vault/dev/vault-datasource.html
:micrometer-registry-guide: https://quarkiverse.github.io/quarkiverse-docs/quarkus-micrometer-registry/dev/index.html
:quarkus-migration-guide: https://github.com/quarkusio/quarkus/wiki/Migration-Guides[Migration Guides]
// .
:create-app-group-id: org.acme
:create-cli-group-id: {create-app-group-id}
// .
// for rendering the final website the attributes are set in the appropriate
// location based on source versions in https://github.com/quarkusio/quarkusio.github.io/
// they are duplicated here to ease the preview when editing in the IDE
// --> No blank lines (it ends the document header)
:idprefix:
:idseparator: -
:icons: font
:generated-dir: ../../../target/quarkus-generated-doc
:doc-examples: ./_examples
:imagesdir: ./images
:includes: ./_includes
:toc: preamble
:iokays-category: quarkus
:iokays-path: modules/ROOT/pages/doc-reference.adoc (3)
:diataxis-type: {type} (4)
:categories: contributing (5)

xref:doc-concept.adoc[Quarkus Documentation concepts] 1

[[title-heading]]
== Title heading

<<title-heading>>

<<title-heading,Title heading description that fits the context of your content>>

xref:<other-file-name>.adoc#title-heading[Title heading]

xref:<name-of-the-file>.adoc[Human-readable label]

[source,java]

examples:
- source: path/to/source/file/SomeClassFile.java 1
  target: prefix-simplified-unique-filename.java 2

examples:
- source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java
  target: telemetry-micrometer-tutorial-example-resource.java

// Source: {{source}}

// Source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java

:categories: contributing, data