adding file type attribute guidance

Author: kalexand-rh

contributing_to_docs/doc_guidelines.adoc

@@ -20,30 +20,33 @@ It is not necessary to update existing content to unwrap lines, but you can remo
 In the Atom editor, you can use `Ctrl`+`J` to undo hard wrapping on a paragraph.
 ====
 
+[id="assembly-file-metadata"]
 == Assembly file metadata
 Every assembly file should contain the following metadata at the top, with no line spacing in between, except where noted:
 
 ----
-[id="<unique-heading-for-assembly>"]                            <1>
-= Assembly title                                                <2>
-include::modules/common-attributes.adoc[]                       <3>
-:context: <unique-context-for-assembly>                         <4>
-                                                                <5>
-toc::[]                                                         <6>
+:_content-type: ASSEMBLY                                        <1>
+[id="<unique-heading-for-assembly>"]                            <2>
+= Assembly title                                                <3>
+include::modules/common-attributes.adoc[]                       <4>
+:context: <unique-context-for-assembly>                         <5>
+                                                                <6>
+toc::[]                                                         <7>
 ----
 
-<1> A unique (within OpenShift docs) anchor id for this assembly. Use lowercase. Example: cli-developer-commands
-<2> Human readable title (notice the '=' top-level header)
-<3> Includes attributes common to OpenShift docs.
+<1> The content type for the file. For assemblies, always use `:_content-type: ASSEMBLY`. Place this attribute before the anchor ID or, if present, the conditional that contains the anchor ID.
+<2> A unique (within OpenShift docs) anchor ID for this assembly. Use lowercase. Example: cli-developer-commands
+<3> Human readable title (notice the '=' top-level header)
+<4> Includes attributes common to OpenShift docs.
 +
 [NOTE]
 ====
 The `{product-name}` and `{product-version}` common attributes are not defined in the `modules/common-attributes.adoc` file. Those attributes are pulled by AsciiBinder from the distro mapping definitions in the https://github.com/openshift/openshift-docs/blob/main/_distro_map.yml[_distro_map.yml] file. See xref:product-name-and-version[Product name and version] for more information on this topic.
 ====
 +
-<4> Context used for identifying headers in modules that is the same as the anchor id. Example: cli-developer-commands.
-<5> A blank line. You *must* have a blank line here before the toc.
-<6> The table of contents for the current assembly.
+<5> Context used for identifying headers in modules that is the same as the anchor ID. Example: cli-developer-commands.
+<6> A blank line. You *must* have a blank line here before the toc.
+<7> The table of contents for the current assembly.
 
 After the heading block and a single whitespace line, you can include any content for this assembly.
 
@@ -54,6 +57,7 @@ Section headers within the assembly must be level 2 ( == ) or lower. When you in
 leveloffsets in the include statements. You can manually add more level 2 or lower section headers in the assembly.
 ====
 
+[id="module-file-metadata"]
 == Module file metadata
 Every module should be placed in the modules folder and should contain the following metadata at the top:
 
@@ -62,13 +66,15 @@ Every module should be placed in the modules folder and should contain the follo
 //
 // * list of assemblies where this module is included              <1>
 
-[id="<module-anchor>_{context}"]                                   <2>
-= Module title                                                     <3>
+:_content-type: <TYPE>                                             <2>
+[id="<module-anchor>_{context}"]                                   <3>
+= Module title                                                     <4>
 ----
 
-<1> List of assemblies in which this module is included.
-<2> A module anchor with {context} that must be lowercase and must match the module's file name.
-<3> Human readable title. To ensure consistency in the results of the
+<1> The content type for the file. Replace `<TYPE>` with the actual type of the module, `CONCEPT`, `REFERENCE`, or `PROCEDURE`. Place this attribute before the anchor ID or, if present, the conditional that contains the anchor ID.
+<2> List of assemblies in which this module is included.
+<3> A module anchor with {context} that must be lowercase and must match the module's file name.
+<4> Human readable title. To ensure consistency in the results of the
 leveloffset values in include statements, you must use a level one heading
 ( = ) for the module title.
 
@@ -79,10 +85,12 @@ Example:
 //
 // * cli_reference/openshift_cli/developer-cli-commands.adoc
 
+:_content-type: REFERENCE
 [id="cli-basic-commands_{context}"]
 = Basic CLI commands
 ----
 
+[id="snippet-file-metadata"]
 == Text snippet file metadata
 Every text snippet should be placed in the snippets folder and should contain the following metadata at the top:
 
@@ -94,9 +102,12 @@ Every text snippet should be placed in the snippets folder and should contain th
 // Text snippet included in the following modules:    <2>
 //
 // * list of modules where this text snippet is included
+
+:_content-type: SNIPPET                               <3>
 ----
 <1> List of assemblies in which this text snippet is included.
 <2> List of modules in which this text snippet is included.
+<1> The content type for the file. For snippets, always use `:_content-type: SNIPPET`. Place this attribute before the anchor ID, the conditional that contains the anchor ID, or the first line of body text.
 
 [NOTE]
 ====
@@ -112,9 +123,30 @@ Example:
 // * installing/installing_azure/installing-azure-default.adoc
 // * installing/installing_gcp/installing-gcp-default.adoc
 
+:_content-type: SNIPPET
 In {product-title} version {product-version}, you can install a cluster on {cloud-provider-first} ({cloud-provider}) that uses the default configuration options.
 ----
 
+== Content type attributes
+
+Each `.adoc` file must contain a `:_content-type:` attribute in its metadata that indicates its file type. This information is used by some publication processes to sort and label files.
+
+Add the attribute from the following list that corresponds to your file type:
+
+* `:_content-type: ASSEMBLY`
+* `:_content-type: CONCEPT`
+* `:_content-type: PROCEDURE`
+* `:_content-type: REFERENCE`
+* `:_content-type: SNIPPET`
+
+Place the attribute in the file metadata. The following list describes the best attribute placement options:
+
+. Directly before the first anchor ID in a file
+. If the first anchor ID is enclosed in a conditional, before the conditional
+. Between the list of assemblies in which this module is included and the first line of body text
+
+The metadata examples contain sample placement for each file type, xref:assembly-file-metadata[assembly], xref:module-file-metadata[module], and xref:snippet-file-metadata[snippet].
+
 == Assembly/module file names
 
 Try to shorten the file name as much as possible _without_ abbreviating important terms that may cause confusion. For example, the `managing-authorization-policies.adoc` file name would be appropriate for an assembly titled "Managing Authorization Policies".
@@ -147,6 +179,7 @@ For example, if you are creating the links in a directory that is two levels dee
 ----
 $ ln -s ../../images/ images
 $ ln -s ../../modules/ modules
+$ ln -s ../../snippets/ snippets
 ----
 +
 Be sure to adjust the number of levels to back up (`../`) depending on how deep your directory is.