Skip to content

adding file type attribute guidance #41331

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 3, 2022
Merged

adding file type attribute guidance #41331

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 50 additions & 17 deletions contributing_to_docs/doc_guidelines.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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:

Expand All @@ -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.

Expand All @@ -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:

Expand All @@ -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]
====
Expand All @@ -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".
Expand Down Expand Up @@ -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.
Expand Down