:_content-type: CONCEPT

[id="documentation-files-generated-from-templates_{context}"]
= Documentation files generated from templates

Every chapter and section defined in the `templates.yaml` file attempts to generate a matching AsciiDoc file. The generated file can either be a reference module or an assembly, depending on its content. The following rules decide the type and name of the generated file:

* If this chapter or section includes no other `subsections` definitions, it generates a reference module. The file name of the module is:
+
[subs="+quotes"]
----
ref___lowercase-title-with-certain-replacements__.adoc
----

* If this chapter or section does include additional `subsections` definitions, it generates an assembly file, which then includes other modules or assemblies in the same directory. The file name of the assembly is:
+
[subs="+quotes"]
----
assembly___lowercase-title-with-certain-replacements__.adoc
----

* If a section is included from another chapter or a section, its file name lists the complete include path:
+
[subs="+quotes"]
----
ref___title-of-section__-__title-of-its-including-parent__.adoc
----

* If no tickets in your project match the `filter` rules defined in this chapter or section, it does not generate any file.
+
Top-level chapters are an exception to this rule. These chapters are generated even if they are empty of release notes, and in that case, they end up being completely empty files. This is a feature that ensures that include directives do not break in your main AsciiDoc file.
+
For example:

** A _Known issues_ chapter uses a filter that looks for tickets with the `Known Issue` doc type. However, none of your tickets in this project is a `Known Issue`. As a result, the `assembly_known-issues.adoc` file is generated as empty.

** A chapter includes subsections that look for three specific components. However, none of your tickets belong to these components. As a result, the section modules are not generated, and the chapter assembly file is generated empty.

** A chapter matches several tickets, the doc text status of all the tickets is incomplete. As a result, the file is generated for the `internal` version of the document with the release note content, but in the `external` version, it is an empty file.
