[[conventions]]
= Documentation conventions

[[file-names]]
== File naming

Name each module file to match the module heading.  
Use dashes between words. Add a prefix with an underscore to indicate the module type:

* `snip-` for snippets
* `con-` for concepts
* `ref-` for references
* `proc-` for procedures
* `assembly-` for assemblies

.Examples
* `snip-intro-custom-resources`  (Snippet of reusable content)
* `con-pod-management.adoc`  (Concept module)
* `proc-creating-logging-filters.adoc`  (Procedure module)
* `ref-list-of-mirrormaker2-resources.adoc`  (Reference module)
* `assembly-deploy-kafka-cluster.adoc`  (Assembly of concepts and procedures)

See the link:https://redhat-documentation.github.io/modular-docs/[Modular Documentation Reference Guide^].

[[content_type]]
== (Required) Content type

Each file requires a content type defined at the top:

[source,asciidoc]
----
:_mod-docs-content-type: ASSEMBLY
:_mod-docs-content-type: PROCEDURE
:_mod-docs-content-type: CONCEPT
:_mod-docs-content-type: REFERENCE
:_mod-docs-content-type: SNIPPET
----

[[ids]]
== (Required) Anchor IDs

Each file requires an anchor ID.  
Use the same name as the file (with dashes) plus a _{context} variable:

[source]
----
[id='name-of-file_{context}']
= Module Heading

First sentence of module.
----

The context variable is defined in the assembly of a guide, such as `:context: str`.
Context variables allow reuse of the same content.
Anchor IDs allow cross-referencing. 
You can also add anchors to subheadings.

[NOTE]
.Other anchor formats (not recommended)
====
Other forms such as `\[[anchor-name]]` or `+[#anchor-name]+` exist, but they have limitations (for example, not supporting variables or certain characters). These can cause build errors. Always use `[id='name']`.
====

[[abstract]]
== (Required) Abstract

Start each file with an introductory paragraph.  
Mark it by adding a `[role="_abstract"]` tag above it.

[[headings-titles]]
== Headings and titles

Use sentence case for module, table, and figure headings.  
For example, _Secrets generated by the operators_, not _Secrets Generated By The Operators_.

[[config-styles]]
== Code and configuration examples

Provide code/configuration examples in AsciiDoc code blocks:

.Configuration example
[source,subs="+quotes"]
------
[source,yaml,subs="+quotes,attributes"] <1>
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    replicas: *3* # \<1> <2>
    # ... <3>
----
------
<1> Source language is `yaml`. Use `subs` for attributes and formatting.  
<2> Use `#` before callout numbers so that the example is copy-friendly.  
<3> Use `# ...` for omitted lines.

[[replaceables]]
== User-replaced values

Style replaceables with angle brackets `< >`.  
For multi-word values, use underscores.  
Use monospace for commands or code.

.User-replaced values quick reference
[cols="50%,50%a",options="header"]
|===
|Value |Shows as
|<my_replaceable>|<my_replaceable>
|<my_code_replaceable>|`<my_code_replaceable>`
|===

TIP: In source blocks, add `subs="+quotes"` so replaceables render correctly.

[[links]]
== Links

Refer to top-level sections of books as chapters, not sections or topics.

.Links quick reference
[options="header"]
|===
|Link type |Use
|External links |\link:github.com[GitHub^]
|Internal links |\xref:doc_id[Section Title]
|===

NOTE: If you use `^` more than once in a paragraph, escape the first with a backslash.

[[images]]
== Images

Store images in `shared/images/`.  
Use this format to add an image to a section:

[source,asciidoc]
----
.Title of image
image:<image_name>.png[<description_of_image>]
----

Inline images can be used in steps:

[source,asciidoc]
----
. My step
+
image:<image_name>.png[<description_of_image>]
----

[[variables]]
== Variables

Variables are defined in `shared/attributes.adoc`.  
They allow single-source updates.  

For example, `:DefaultKafkaVersion:` sets the default Kafka version and `{DefaultKafkaVersion}` is used to insert it into configuration examples.

