Skip to content
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

Docs guidelines: Move include for common attributes above the title #62912

Merged
merged 1 commit into from
Aug 16, 2023
Merged

Docs guidelines: Move include for common attributes above the title #62912

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
12 changes: 6 additions & 6 deletions contributing_to_docs/doc_guidelines.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[id="contributing-to-docs-doc-guidelines"]
= Documentation guidelines
include::_attributes/common-attributes.adoc
= Documentation guidelines
:toc: macro

The documentation guidelines for OpenShift 4 build on top of the
Expand Down Expand Up @@ -37,23 +37,23 @@ Every assembly file should contain the following metadata at the top, with no li
----
:_content-type: ASSEMBLY <1>
[id="<unique-heading-for-assembly>"] <2>
= Assembly title <3>
include::_attributes/common-attributes.adoc[] <4>
include::_attributes/common-attributes.adoc[] <3>
= Assembly title <4>
:context: <unique-context-for-assembly> <5>
<6>
toc::[] <7>
----

<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.
<2> A unique (within OpenShift docs) anchor ID for this assembly. Use lowercase. Example: cli-developer-commands.
<3> Includes attributes common to OpenShift docs.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just noticed this, but should the note be under #3 since it is sort of referring to the attributes not being in the attributes file? I'm sorry I didn't see this earlier, but since #3 and #4 have switched places, I think the note should move up with #3.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kcarmichael08 - fixed! Good spot!

+
[NOTE]
====
The `{product-title}` and `{product-version}` common attributes are not defined in the `_attributes/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 title and version] and xref:attribute-files[attribute files] for more information on this topic.
====
+
<4> Human readable title (notice the `=` top-level header).
<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.
Expand Down