{% if metadata -%}
:_newdoc-version: {{generator_version}}
:_template-generated: {{current_day}}
{%- endif %}
////
Base the file name and the ID on the module title. For example:
* file name: con_my-concept-module-a.adoc
* ID: [id="my-concept-module-a_{context}"]
* Title: = My concept module A
////

////
Indicate the module type in one of the following
ways:
Add the prefix con- or con_ to the file name.
Add the following attribute before the module ID:
////
{% if metadata -%}
:_mod-docs-content-type: CONCEPT
{%- endif %}

////
The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken.

The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide.
////

{% if simplified -%}
[id="{{module_anchor}}"]
{%- else -%}
[id="{{module_anchor}}_{context}"]
{%- endif %}
= {{module_title}}
////
In the title of concept modules, include nouns or noun phrases that are used in the body text. This helps readers and search engines find the information quickly. Do not start the title of concept modules with a verb. See also _Wording of headings_ in _The IBM Style Guide_.

Be sure to include a line break between the title and the module introduction.
////

{% if examples -%}
Write a short introductory paragraph that provides an overview of the module.

The contents of a concept module give the user descriptions and explanations needed to understand and use a product.

* Look at nouns and noun phrases in related procedure modules and assemblies to find the concepts to explain to users.
* Explain only things that are visible to users. Even if a concept is interesting, it probably does not require explanation if it is not visible to users.
* Avoid including action items. Action items belong in procedure modules. However, in some cases a concept or reference can include suggested actions when those actions are simple, are highly dependent on the context of the module, and have no place in any procedure module. In such cases, ensure that the heading of the concept or reference remains a noun phrase and not a gerund.

////
Include titles and alternative text descriptions for images.
Alternative text should provide a textual, complete description of the image as a full sentence.
Images should never be the sole means of conveying information and should only supplement the text.
Avoid screenshots or other images that might quickly go out of date and that create a maintenance burden on documentation.
Provide text equivalents for every diagram, image, or other non-text element. Avoid using images of text instead of actual text.
////
//.Image title
//image::image-file.png[A textual representation of the essential information conveyed by the image.]
{%- endif %}

[role="_additional-resources"]
.Additional resources
////
Optional. Delete if not used.
////
{% if examples -%}
* A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros.
* For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
{%- endif %}
