[[style-guide]]
= Style guidelines

[[config-styles]]
== Adding code and configuration examples

The Strimzi documentation contains many code and configuration examples.
Examples are a useful way of demonstrating a process.

If you want to add example code and configuration to your contribution, use the following format in an asciidoc code block.

.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> Syntax for the example. Here the source language is `yaml`. Use _subs_ to apply attribute (`attributes`) and formatting (`subs`).
In this example, `{KafkaApiVersion}` is substituted with an attribute value specified in the `/shared/attributes.adoc` file.
If _quotes_ is specified in _subs_, asciidoc formatting is applied to the code block. Here, bold is applied to the *3* value of `replicas`. If _quotes_ isn't used, asciidoc formatting is ignored in the code block.
<2> Add callouts to describe a line of code or configuration. Use a hash (`#`) before the callout number so that the example is copy-friendly.
<3> Use a hash and ellipsis (`# ...`) to show that part of the code or configuration has been omitted.

[[headings-titles]]
== Styling headings and titles

Uses sentence-case headings for modules, tables, and figures.
For example, _Secrets generated by the operators_ not _Secrets Generated By The Operators_.

[[ids]]
== Section IDs

Each file in the documentation requires an ID.
The ID takes the form `[id="name-of-file-{context}"]`.

[[replaceables]]
== User-replaced values

Style user-replaced values (replaceables) with angle brackets (< >).
Use underscores ( _ ) for multi-word values.
If you are referencing code or commands, also use `monospace`.

.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: If adding a user-replaced value within a source code block, add
`subs="+quotes"` to the source tag for it to render. (For example : `++[source,shell,subs="+quotes"]++`).

== Styling links

Refer links to the 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 the caret syntax (^) more than once in a single paragraph, you may need to
escape the first occurrence with a backslash.

== Adding images

Add images for screenshots, diagrams and so on in the following format:

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

You can also add inline images, such as in steps for procedures:

.Adding an inline image to a step
[source,asciidoc]
----
. My step.
+
.My inline image. 
image:<image_name>.png[<description_of_image>]
----