diff --git a/contributing_to_docs/doc_guidelines.adoc b/contributing_to_docs/doc_guidelines.adoc index b7512c6da901..82b13da37137 100644 --- a/contributing_to_docs/doc_guidelines.adoc +++ b/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=""] <1> -= Assembly title <2> -include::modules/common-attributes.adoc[] <3> -:context: <4> - <5> -toc::[] <6> +:_content-type: ASSEMBLY <1> +[id=""] <2> += Assembly title <3> +include::modules/common-attributes.adoc[] <4> +:context: <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="_{context}"] <2> -= Module title <3> +:_content-type: <2> +[id="_{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 `` 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.