mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-07 00:48:01 +01:00
2321 lines
90 KiB
Plaintext
2321 lines
90 KiB
Plaintext
:toc: macro
|
|
[id="contributing-to-docs-doc-guidelines"]
|
|
= Documentation guidelines
|
|
include::_attributes/common-attributes.adoc[]
|
|
|
|
toc::[]
|
|
|
|
The documentation guidelines for OpenShift 4 build on top of the
|
|
link:https://redhat-documentation.github.io/modular-docs/[_Red Hat modular docs reference guide_].
|
|
|
|
[NOTE]
|
|
====
|
|
These _Documentation guidelines_ are primarily concerned with the modular structure and AsciiDoc/AsciiBinder requirements for building OpenShift documentation. For general style guidelines in OpenShift docs, see the following:
|
|
|
|
* Primary source: link:https://www.ibm.com/docs/en/ibm-style[_IBM Style_]
|
|
* Supplementary source: link:https://redhat-documentation.github.io/supplementary-style-guide/[_Red Hat supplementary style guide for product documentation_]
|
|
|
|
When looking for style guidance, reference the _Red Hat supplementary style guide for product documentation_ first, because it overrides certain guidance from the _IBM Style_ guide.
|
|
====
|
|
|
|
|
|
== General file guidelines
|
|
|
|
* Set your editor to strip trailing whitespace.
|
|
* Do *not* hard wrap lines at 80 characters (or at any other length).
|
|
+
|
|
It is not necessary to update existing content to unwrap lines, but you can remove existing hard wrapping from any lines that you are currently working in.
|
|
+
|
|
[TIP]
|
|
====
|
|
In the Pulsar editor, you can use `Ctrl`+`J` to undo hard wrapping on a paragraph.
|
|
====
|
|
|
|
[id="assembly-file-metadata"]
|
|
== Assembly file metadata
|
|
Every assembly file must contain the following metadata at the top, with no blank lines, except where noted:
|
|
|
|
----
|
|
:_mod-docs-content-type: ASSEMBLY <1>
|
|
[id="<assembly-anchor-id>"] <2>
|
|
= Assembly title <3>
|
|
<4>
|
|
include::_attributes/common-attributes.adoc[] <5>
|
|
<6>
|
|
:context: <assembly-context> <7>
|
|
<8>
|
|
toc::[] <9>
|
|
----
|
|
<1> The content type for the file. For assemblies, always use `:_mod-docs-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 and hyphens, for example: `cli-developer-commands`.
|
|
<3> Human readable title (notice the `=` top-level header).
|
|
+
|
|
[NOTE]
|
|
====
|
|
* Do not use backticks or other markup in assembly headings. You can use backticks or other markup in the title for a block, such as a code block `.Example` or a table `.Description` title.
|
|
* Do not use "Optional:" to prefix an assembly title. According to IBM Style Guide, this practice is reserved for optional steps and code callouts.
|
|
* With content reuse and modular documentation, you cannot be certain that all future use of an assembly will remain optional. For more information, see link:https://www.ibm.com/docs/en/ibm-style?topic=format-procedures#indicating-optional-and-conditional-steps["Indicating optional and conditional steps (Requires IBM Style login)"].
|
|
* The assembly title, which is the first line of the document, is the only level 1 ( `=` ) title.
|
|
Section headers within the assembly must be H2 ("Level 1" in AsciiDoc terminology), formatted as `==`. When you include modules, you must add leveloffsets in the include statements. You can manually add more H2 (`==`) section headers in the assembly.
|
|
====
|
|
<4> You must include a blank line after H1 ("Level 0" in AsciiDoc terminology) headings.
|
|
<5> Includes attributes common to OpenShift docs.
|
|
+
|
|
[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.
|
|
* If you use a variable in the title of the first assembly in a section, move the include attributes directive above the anchor ID in this assembly. Otherwise, the variable will not render correctly on our documentation portals. For example:
|
|
+
|
|
[source,text]
|
|
----
|
|
:_mod-docs-content-type: ASSEMBLY
|
|
include::_attributes/common-attributes.adoc[]
|
|
|
|
[id="installing-ibm-cloud-private"]
|
|
= Installing a private cluster on {ibm-cloud-title}
|
|
|
|
:context: installing-ibm-cloud-private
|
|
|
|
toc::[]
|
|
----
|
|
====
|
|
<6> You must include a blank line after each `include::` statement.
|
|
<7> Context used for identifying headers in modules that is the same as the anchor ID. Use lowercase and hyphens, for example `cli-developer-commands`.
|
|
<8> A blank line. You *must* have a blank line here before the `toc::[]`.
|
|
+
|
|
After the heading block and a single whitespace line, you can include any content for this assembly.
|
|
<9> The table of contents for the current 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:
|
|
|
|
----
|
|
// Module included in the following assemblies:
|
|
//
|
|
// * list of assemblies where this module is included <1>
|
|
|
|
:_mod-docs-content-type: <TYPE> <2>
|
|
[id="<module-anchor>_{context}"] <3>
|
|
= Module title <4>
|
|
<5>
|
|
----
|
|
|
|
<1> List of assemblies in which this module is included.
|
|
<2> 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.
|
|
<3> The anchor ID with `_{context}` must be lowercase and 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 1 heading
|
|
( = ) for the module title.
|
|
+
|
|
[NOTE]
|
|
====
|
|
* Do not use backticks or other markup in module headings. You can use backticks or other markup in the title for a block, such as a code block `.Example` or a table `.Description` title.
|
|
* Do not use "Optional:" to prefix a module title. According to IBM Style, this practice is reserved for optional steps and code callouts.
|
|
* With content reuse and modular documentation, you cannot be certain that all future use of a module will remain optional. For more information, see link:https://www.ibm.com/docs/en/ibm-style?topic=format-procedures#indicating-optional-and-conditional-steps["Indicating optional and conditional steps (Requires IBM Style login)"].
|
|
====
|
|
<5> You must include a blank line after H1 ("Level 0" in AsciiDoc terminology) headings.
|
|
|
|
[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:
|
|
|
|
----
|
|
// Text snippet included in the following assemblies: <1>
|
|
//
|
|
// * list of assemblies where this text snippet is included
|
|
//
|
|
// Text snippet included in the following modules: <2>
|
|
//
|
|
// * list of modules where this text snippet is included
|
|
|
|
:_mod-docs-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.
|
|
<3> The content type for the file. For snippets, always use `:_mod-docs-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]
|
|
====
|
|
An anchor ID and human readable title are not required metadata. This type of component is text only and not intended to be published or cross referenced on its own. See <<writing-text-snippets>>.
|
|
====
|
|
|
|
Example:
|
|
|
|
----
|
|
// Text snippet included in the following assemblies:
|
|
//
|
|
// * installing/installing_aws/ipi/installing-aws-default.adoc
|
|
// * installing/installing_azure/installing-azure-default.adoc
|
|
// * installing/installing_gcp/installing-gcp-default.adoc
|
|
|
|
:_mod-docs-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 `:_mod-docs-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:
|
|
|
|
* `:_mod-docs-content-type: ASSEMBLY`
|
|
* `:_mod-docs-content-type: CONCEPT`
|
|
* `:_mod-docs-content-type: PROCEDURE`
|
|
* `:_mod-docs-content-type: REFERENCE`
|
|
* `:_mod-docs-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].
|
|
|
|
[id="attribute-files"]
|
|
== Attribute files
|
|
|
|
All attribute files must be placed in the `_attributes` directory. In most cases involving OpenShift Container Platform or OKD, add attributes to the `common-attributes.adoc` file instead of creating or using a separate attributes file. Before you add an attribute, review the contents of the `common-attributes.adoc` file to ensure that it is not already defined.
|
|
|
|
[IMPORTANT]
|
|
====
|
|
If you think that you need a separate attributes file, check with the docs team before you create it.
|
|
====
|
|
|
|
It is acceptable to group related attributes in the `common-attributes.adoc` file under a comment, as shown in the following example:
|
|
|
|
----
|
|
//gitops
|
|
:gitops-title: Red Hat OpenShift GitOps
|
|
:gitops-shortname: GitOps
|
|
----
|
|
|
|
It is also acceptable to enclose attributes in a xref:product-name-and-version[distro-based] conditional, but you must place attribute definitions for the `openshift-enterprise` distro first. The following example shows how to set a different value for the `:op-system-base:` attribute for OKD:
|
|
|
|
----
|
|
:op-system-base: RHEL
|
|
ifdef::openshift-origin[]
|
|
:op-system-base: Fedora
|
|
endif::[]
|
|
----
|
|
|
|
[NOTE]
|
|
====
|
|
When backporting content that contains IBM-related attributes to `enterprise-4.13` and earlier branches, you might need to create manual cherry picks because IBM-related attributes names are not consistent with later release branches.
|
|
====
|
|
|
|
== 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".
|
|
|
|
== Directory names
|
|
|
|
When creating a new directory, follow these guidelines:
|
|
|
|
* Use underscores to separate multiple-word directory names, for example, `backup_and_restore`.
|
|
* Create the symbolic links for the `images`, `modules`, `snippets` and `_attributes` directories. See xref:symbolic-links[Symbolic links] for instructions.
|
|
* Use the CLI (`mkdir <directory_name>`) instead of an editor, to avoid potential syncing issues.
|
|
* Do not copy another directory or its symbolic links when creating the new directory, to avoid issues with the symbolic links.
|
|
* Do not create or rename a top-level directory in the repository and topic map without checking with the docs program manager first. If a book is being created or modified, there are changes on the Customer Portal that must also be made.
|
|
|
|
[[symbolic-links]]
|
|
=== Symbolic links
|
|
|
|
When creating a new directory or subdirectory, you must create these four symbolic links in it:
|
|
|
|
* An `images` symbolic link to the top-level `images/` directory
|
|
* A `modules` symbolic link to the top-level `modules/` directory
|
|
* A `snippets` symbolic link to the top-level `snippets/` directory
|
|
* An `_attributes` symbolic link to the top-level `_attributes/` directory
|
|
|
|
[IMPORTANT]
|
|
====
|
|
If these symbolic links aren't included in an assembly's directory, any images in that assembly or its modules are not included properly when building the docs.
|
|
====
|
|
|
|
To create the symbolic links:
|
|
|
|
. Navigate to the directory that you need to add the links in.
|
|
. Use the following command to create a symbolic link:
|
|
+
|
|
----
|
|
$ ln -s <target_directory> <link_name>
|
|
----
|
|
+
|
|
For example, if you are creating the links in a directory that is two levels deep, such as `cli_reference/openshift_cli`, use the following commands:
|
|
+
|
|
----
|
|
[openshift-docs ~]$ cd cli_reference/openshift_cli
|
|
[openshift_cli ~]$ ln -s ../../images/ images
|
|
[openshift_cli ~]$ ln -s ../../modules/ modules
|
|
[openshift_cli ~]$ ln -s ../../snippets/ snippets
|
|
[openshift_cli ~]$ ln -s ../../_attributes/ _attributes
|
|
----
|
|
+
|
|
Be sure to adjust the number of levels to back up (`../`) depending on how deep your directory is.
|
|
|
|
If you accidentally create an incorrect symbolic link, you can remove that link by using `unlink <link_name>`. For example, the following commands unlink an incorrect `images` symbolic link in the `cli_reference/openshift_cli` directory:
|
|
|
|
----
|
|
[openshift-docs ~]$ cd cli_reference/openshift_cli
|
|
[openshift_cli ~]$ unlink images
|
|
----
|
|
|
|
== Assembly/module titles and section headings
|
|
|
|
Use sentence case in all titles and section headings. See http://www.titlecase.com/ or https://convertcase.net/ for a conversion tool.
|
|
|
|
Try to be as descriptive as possible with the title or section headings without making them unnecessarily long. For assemblies and task modules, use a gerund form in headings, such as:
|
|
|
|
* Creating
|
|
* Managing
|
|
* Using
|
|
|
|
Do not use "Overview" as a heading.
|
|
|
|
Do not use backticks or other markup in assembly or module headings.
|
|
|
|
Do not use special characters or symbols in titles. Symbols and special characters in titles can cause rendering errors in the HTML output.
|
|
|
|
Use only one link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/#section-level-syntax[Level 0] (`=`) heading in any file.
|
|
Level 0 headings map to an H1 or `<h1>` in HTML.
|
|
|
|
Do not use Level 2 (H3) headings (`===`) or lower in any files.
|
|
|
|
=== Anchoring titles and section headings
|
|
|
|
All titles and section headings must have an anchor ID. The anchor ID must be similar to the title or section heading. Do not include line spaces between the anchor ID and the section title.
|
|
|
|
.Example anchor ID and heading
|
|
----
|
|
[id="configuring-alert-notifications"] <1>
|
|
= Configuring alert notifications <2>
|
|
----
|
|
<1> Anchor ID
|
|
<2> Title/section heading
|
|
|
|
The following anchor IDs also require use of the `_{context}` variable:
|
|
|
|
* **All** headings in module files
|
|
* **Only** subsections in assembly files (but not the link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/#section-level-syntax[Level 0] heading/main title)
|
|
|
|
When called, the `_{context}` variable is resolved into the value declared in the `:context:` attribute in the corresponding assembly file. This enables cross-referencing of IDs in context to a specific assembly and is useful when a module is included in multiple assemblies.
|
|
|
|
[NOTE]
|
|
====
|
|
The `{context}` variable must be preceded by an underscore (`_`) when declared in an anchor ID.
|
|
====
|
|
|
|
==== Anchoring in assembly files
|
|
|
|
===== Assembly titles (Level 0 headings)
|
|
|
|
For the single link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/#section-level-syntax[Level 0] heading (`=`) of an assembly file, **do not** add a `_{context}` variable to the end of the anchor ID.
|
|
|
|
.Example anchor ID for the Level 0 heading of an assembly file
|
|
----
|
|
[id="configuring-alert-notifications"]
|
|
= Configuring alert notifications
|
|
----
|
|
|
|
[NOTE]
|
|
====
|
|
This guideline includes an exception to the link:https://redhat-documentation.github.io/modular-docs/#nesting-assemblies[_Red Hat modular docs reference guide_], which shows including the `{context}` variable for Level 0 headings of assemblies as well.
|
|
====
|
|
|
|
The anchor ID for the assembly title should match the `:context:` set in the xref:assembly-file-metadata[assembly file metadata].
|
|
|
|
===== Assembly subsections (Level 1 headings)
|
|
|
|
For any Level 1 _subsections_ in an assembly (i.e. `==`), add a `_{context}` variable to the end of anchor IDs:
|
|
|
|
.Example anchor ID for a Level 1 heading (subsection) of an assembly file
|
|
----
|
|
[id="editing-alerts_{context}"]
|
|
== Editing alerts
|
|
----
|
|
|
|
This ensures a unique anchor ID across the repo.
|
|
|
|
Do not use H3 headings (`===`) or lower in any files.
|
|
|
|
==== Anchoring in module files
|
|
|
|
You must add the `_{context}` variable to the end of each anchor ID in module files, for any section level:
|
|
|
|
.Example anchor ID for a module file Level 0 (`=`) heading/main title
|
|
----
|
|
[id="sending-notifications-to-external-systems_{context}"]
|
|
= Sending notifications to external systems
|
|
----
|
|
|
|
.Example anchor ID for a Level 1 (`==`) subsection heading
|
|
----
|
|
[id="deployment-scaling-benefits_{context}"]
|
|
== Deployment and scaling benefits
|
|
----
|
|
|
|
=== Anchoring "Prerequisites", "Additional resources", and "Next steps" titles in assemblies
|
|
|
|
For anchor IDs of "Prerequisites", "Additional resources", and "Next steps" titles in assemblies, use the prefixes `prerequisites_`, `additional-resources_`, or `next-steps_` followed by the `{context}` variable. Using this variable automatically matches the value assigned to the `:context:` attribute in the assembly, which ensures a unique ID across the repo. Use an underscore (`_`) between the prefix and `{context}` variable.
|
|
|
|
.Example unique anchor ID for a "Prerequisites" title
|
|
----
|
|
[id="prerequisites_{context}"]
|
|
== Prerequisites
|
|
----
|
|
|
|
.Example unique anchor ID for an "Additional resources" title
|
|
----
|
|
[role="_additional-resources"]
|
|
[id="additional-resources_{context}"]
|
|
== Additional resources
|
|
----
|
|
|
|
.Example unique anchor ID for a "Next steps" title
|
|
----
|
|
[id="next-steps_{context}"]
|
|
== Next steps
|
|
----
|
|
|
|
=== Discrete headings
|
|
|
|
Do not use discrete headings. If you have several short subjects to talk about that you want headings on, you can use list formatting. You could also consider bulleted lists, or revising your overall document structure to highlight the topics with headings.
|
|
|
|
.Example list formatting in a module or assembly
|
|
----
|
|
OVN node switch::
|
|
A virtual switch named `<node-name>`.
|
|
----
|
|
|
|
== Writing assemblies
|
|
An _assembly_ is a collection of modules that describes how to accomplish a user story. Module content is added to an assembly using the `include` directive. The `include` directive includes contents from another file in the current document. Files can be modules or snippets formatted in AsciiDoc, or another text format such as YAML.
|
|
|
|
An `include` directive must always be on its own line and be followed by a blank line.
|
|
|
|
.Standard module include syntax
|
|
[source,text]
|
|
----
|
|
include::modules/module-filename.adoc[leveloffset=+1] <1>
|
|
<2>
|
|
----
|
|
<1> `[leveloffset=]` link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/#manipulate-heading-levels-with-leveloffset[is relative], and changes the header level of included content.
|
|
<2> You must include a blank line after each `include::` statement.
|
|
|
|
[IMPORTANT]
|
|
====
|
|
Including link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-lines/[lines by content ranges] can lead to content errors when the included file is subsequently updated and is not permitted.
|
|
====
|
|
|
|
Avoid link:https://redhat-documentation.github.io/modular-docs/#nesting-assemblies[nesting assemblies] in other assembly files. You can create more complicated document structures by modifying the link:https://github.com/openshift/openshift-docs/tree/main/_topic_maps[topic maps].
|
|
|
|
For more information about forming assemblies, see the
|
|
link:https://redhat-documentation.github.io/modular-docs/#forming-assemblies[_Red Hat modular docs reference guide_] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc[assembly template].
|
|
|
|
[NOTE]
|
|
====
|
|
When using the "Prerequisites", "Next steps", or "Additional resources" headings in an assembly, use `==` formatting, such as `== Prerequisites` or `== Additional resources`. Use of this heading syntax at the assembly level indicates that the sections relate to the whole assembly.
|
|
|
|
Only use `.` formatting (`.Additional resources`) to follow a module in an assembly. Because you cannot use the xrefs in modules, this functions as a _trailing include_ at the assembly level, where the `.` formatting of the `include` statement indicates that the resource applies specifically to the module and not to the assembly.
|
|
====
|
|
|
|
=== Including by tags
|
|
You can use `tag` attributes to link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions[define regions of a file and include by tag instead of the whole file.] This enables you to make conditional modifications to existing modules instead of duplicating content. When creating a tag, use a tag name that makes it easy to understand where the content defined will be included.
|
|
|
|
* In assembly files, use the `tags` (plural) attribute when there is more than one tag specified. Use the `tag` (singular) attribute when there is only one tag. For example:
|
|
+
|
|
.Singular tagged module include syntax
|
|
[source,text]
|
|
====
|
|
\include::modules/module-with-tag-filename.adoc[leveloffset=+1,tag=TagName]
|
|
====
|
|
+
|
|
.Plural tagged module include syntax
|
|
[source,text]
|
|
====
|
|
\include::modules/module-with-tags-filename.adoc[leveloffset=+1,tags=TagName;Mode1;!Mode2]
|
|
====
|
|
|
|
* In the module files, use `//` before the tag directives in asciidoc text and a `#` before tag directives in YAML. For example:
|
|
+
|
|
.Included file tag directives
|
|
[source,text]
|
|
----
|
|
// tag::TagName[]
|
|
== Tagging regions
|
|
|
|
Tags are useful when you want to identify specific regions of a file to include. You can then select the lines between the boundaries of the include tag/end directives to include using the tags attribute.
|
|
|
|
In the included file, the tag directives (e.g., tag::<tag_name>[] and end::<tag_name>[]) must follow a word boundary and precede a space character or the end of line. The tag name must not be empty and must consist exclusively of non-space characters.
|
|
|
|
.Example CR
|
|
[source,yaml]
|
|
--
|
|
spec:
|
|
# tag::Mode1[]
|
|
mode: openshift
|
|
# end::Mode1[]
|
|
# tag::Mode2[]
|
|
mode: openshift-network
|
|
# end::Mode2[]
|
|
--
|
|
// end::TagName[]
|
|
----
|
|
+
|
|
[WARNING]
|
|
====
|
|
The use of a wildcard (`*`) is not fully supported by PV1. Verify that access.redhat.com builds and docs.openshift.com builds are including or excluding content as expected if you try to use them.
|
|
====
|
|
|
|
You can filter out the regions defined by a `tag` attribute by using link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/#tag-filtering[expressions] in place of or in conjunction with the tag name. If you add tag defined conditional content to a module with no existing tags, you must update existing includes of the file you are changing to exclude your content.
|
|
|
|
== Writing concepts
|
|
A _concept_ contains information to support the tasks that users want to do and
|
|
must not include task information like commands or numbered steps. In most
|
|
cases, create your concepts as individual modules and include them in
|
|
appropriate assemblies.
|
|
|
|
Avoid using gerunds in concept titles. "About <concept>"
|
|
is a common concept module title.
|
|
|
|
For more information about creating concept modules, see the
|
|
link:https://redhat-documentation.github.io/modular-docs/#creating-concept-modules[_Red Hat modular docs reference guide_] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc[concept template].
|
|
|
|
== Writing procedures
|
|
A _procedure_ contains the steps that users follow to complete a single process or task. Procedures contain ordered steps and explicit commands. In most cases, create your procedures as individual modules and include them in appropriate assemblies.
|
|
|
|
Use a gerund in the procedure title, such as "Creating".
|
|
|
|
[IMPORTANT]
|
|
====
|
|
Modules cannot contain xrefs. If you _must_ use a link in your module, use the `link` attribute type and treat it as an external reference.
|
|
|
|
Use version attributes for the maintainability of xrefs and links whenever you can.
|
|
====
|
|
|
|
For more information about writing procedures, see the
|
|
link:https://redhat-documentation.github.io/modular-docs/#con-creating-procedure-modules_writing-mod-docs[_Red Hat modular docs reference guide_] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc[procedure template].
|
|
|
|
[NOTE]
|
|
====
|
|
When needed, use the _<.section_title>_ syntax suppress TOC formatting within a module, for example, `.Prerequisites`, `.Procedure`, `.Next steps`, or `.Additional resources`. Do not use the heading-level syntax, such as `==`, for these headings in modules.
|
|
====
|
|
|
|
[id="writing-text-snippets"]
|
|
== Writing text snippets
|
|
A _text snippet_ is an optional component that lets you reuse content in multiple modules and assemblies. Text snippets are not a substitute for modules but instead are a more granular form of content reuse. While a module is content that a reader can understand on its own (like an article) or as part of a larger body of work (like an assembly), a text snippet is not self-contained and is not intended to be published or cross referenced on its own.
|
|
|
|
[IMPORTANT]
|
|
====
|
|
Like modules, text snippets cannot contain xrefs. If you _must_ use a link in your snippet, use the `link` attribute type and treat it as an external reference. It is recommended to use version attributes for maintainability of the link.
|
|
====
|
|
|
|
In the context of modules and assemblies, text snippets do not include headings or anchor IDs. Examples include the following:
|
|
|
|
* Admonitions that appear in multiple modules.
|
|
* An introductory paragraph that appears in multiple assemblies.
|
|
* The same series of steps that appear in multiple procedure modules.
|
|
* A deprecation statement that appears in multiple sets of release notes.
|
|
|
|
Example:
|
|
|
|
You could write the following paragraph once and include it in each assembly that explains how to install a cluster using the installer-provisioned default values:
|
|
|
|
[source,text]
|
|
----
|
|
In {product-title} version {product-version}, you can install a cluster on {cloud-provider-first} ({cloud-provider}) that uses the default configuration options.
|
|
----
|
|
|
|
[NOTE]
|
|
====
|
|
In the example, `cloud-provider-first` and `cloud-provider` are not defined by the `common-attributes` module. If you use an attribute that is not common to OpenShift docs, make sure to define it locally in either the assembly or module, depending on where the text snippet is included. Because of this, consider adding all attributes that you add to snippets to the `common-attributes.adoc` file.
|
|
====
|
|
|
|
For more information about creating text snippets, see the
|
|
link:https://redhat-documentation.github.io/modular-docs/#using-text-snippets[_Red Hat modular docs reference guide_].
|
|
|
|
[id="Auto-generated-content"]
|
|
== Automatically generated content
|
|
|
|
The following content is automatically generated in each release and must not be manually edited:
|
|
|
|
* The OpenShift CLI (`oc`) command references `modules/oc-by-example-content.adoc` and `modules/oc-adm-by-example-content.adoc`.
|
|
* The following API references content in the `rest_api` folder: the contents of all `<topic>_apis` subfolders and the `rest_api/objects/index.adoc` and `rest_api/index.adoc` assemblies.
|
|
* OpenShift Virtualization runbook modules: `modules/virt-runbook-<runbook>.adoc`.
|
|
|
|
[NOTE]
|
|
====
|
|
If the content in these files needs to be updated, the update must be made in the applicable code repository where these files are generated from. The updates are reflected when the files are generated the next time, for example a future release. For help with where to make the updates, you can contact https://github.com/bergerhoffer[Andrea Hoffer] for the CLI docs, https://github.com/jboxman-rh[Jason Boxman] for the API docs, or https://github.com/apinnick[Avital Pinnick] for the OpenShift Virtualization runbooks.
|
|
====
|
|
|
|
[id="using-conscious-language"]
|
|
== Using conscious language
|
|
|
|
To assist with the removal of the problematic word "master" from the documentation, use the following terminology when referring to OpenShift control plane nodes:
|
|
|
|
[options="header"]
|
|
|===
|
|
|Branch |Control plane node reference
|
|
|
|
|All supported versions
|
|
|Control plane node
|
|
|
|
|===
|
|
|
|
You can replace "node" in the preceding examples with "machine", "host", or another suitable description.
|
|
|
|
In general text, use the term "control plane machine" in place of "master machine"; use the term "compute machine" in place of "worker machine". Be mindful of certain valid code entities, such as `master` role, `worker` role, and `infra` role.
|
|
|
|
[id="adding-a-subsection-on-making-open-source-more-inclusive"]
|
|
=== Adding a subsection on making open source more inclusive
|
|
|
|
Because the link to the "Making open source more inclusive" content has been moved to the footer of docs.redhat.com, do not include a separate module related to this content.
|
|
|
|
[id="product-name-and-version"]
|
|
== Product title and version
|
|
|
|
When possible, generalize references to the product name and/or version by using
|
|
the `{product-title}` and/or `{product-version}` attributes. These attributes
|
|
are pulled by AsciiBinder from the OpenShift distribution, or _distro_, mapping definitions in the
|
|
https://github.com/openshift/openshift-docs/blob/main/_distro_map.yml[_distro_map.yml]
|
|
file.
|
|
|
|
The `{product-title}` comes from the first `name:` field in a distro mapping,
|
|
while the associated `{product-version}` comes from the `name:` fields on any
|
|
`branches:` defined.
|
|
|
|
How these attributes render is dependent on which distro and branch build you
|
|
are viewing. The following table shows the current distros and the
|
|
possible values for `{product-title}` and `{product-version}`, depending on the branch:
|
|
|
|
[options="header"]
|
|
|===
|
|
|Distro |`{product-title}` |`{product-version}`
|
|
|
|
|`openshift-origin`
|
|
|OKD
|
|
a|* 3.6, 3.7, 3.9, 3.10, 3.11
|
|
* 4.8, 4.9, 4.10, 4.11, 4.12, 4.13, 4.14, 4.15, 4.16, 4.17, 4.18, 4.19
|
|
* 4 for the `latest/` build from the `main` branch
|
|
|
|
|`openshift-enterprise`
|
|
|OpenShift Container Platform
|
|
a|* 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.9, 3.10, 3.11
|
|
* 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7, 4.8, 4.9, 4.10, 4.11, 4.12, 4.13, 4.14, 4.15, 4.16, 4.17, 4.18, 4.19, 4.20
|
|
|
|
|`openshift-dedicated`
|
|
|OpenShift Dedicated
|
|
a|* No value set for the latest `dedicated/` build from the `enterprise-4.19` branch
|
|
* 3 for the `dedicated/3` build from the `enterprise-3.11` branch
|
|
|
|
|`openshift-rosa`
|
|
|Red Hat OpenShift Service on AWS
|
|
|No value set for the `rosa/` build from the `enterprise-4.19` branch
|
|
|
|
|`openshift-online`
|
|
|OpenShift Online
|
|
|Pro
|
|
|===
|
|
|
|
For example:
|
|
|
|
----
|
|
You can deploy applications on {product-title}.
|
|
----
|
|
|
|
This is a safe statement that could appear in probably any of the builds, so an
|
|
https://github.com/openshift/openshift-docs/blob/main/contributing_to_docs/contributing.adoc#conditional-text-between-products[ifdef/endif
|
|
statement] is not necessary. For example, if you were viewing a build for the
|
|
`openshift-enterprise` distro (for any of the distro-defined branches), this
|
|
would render as:
|
|
|
|
> You can deploy applications on OpenShift Container Platform.
|
|
|
|
And for the `openshift-origin` distro:
|
|
|
|
> You can deploy applications on OKD.
|
|
|
|
Considering that we use distinct branches to keep content for product versions separated, global use of `{product-version}` across all branches is probably less useful, but it is available if you come across a requirement for it. Just consider how it will render across any branches that the content appears in.
|
|
|
|
If it makes more sense in context to refer to the major version of the product instead of a specific minor version (for example, if comparing how something in OpenShift Container Platform 4 differs from OpenShift Container Platform 3), just use the major version number. Do not prepend with a `v`, as in `v3` or `v4`.
|
|
|
|
[NOTE]
|
|
====
|
|
Other common attribute values are defined in the `_attributes/common-attributes.adoc` file. Where possible, generalize references to those values by using the common attributes. For example, use `{cluster-manager-first}` to refer to Red Hat OpenShift Cluster Manager. If you need to add an attribute to the `_attributes/common-attributes.adoc` file, open a pull request to add it to the attribute list. Do not create a separate attributes file without first consulting the docs team.
|
|
====
|
|
|
|
[id="third-party-vendor-product-names"]
|
|
== Third-party vendor product names
|
|
|
|
Red Hat integrates with many third-party vendor products. For certain integrated products, third-party vendor staff might have access to certain Red Hat resources and be contactable within Red Hat. On other occasions, common open-source products might be widely used across IT infrastructure providers, so Red Hat might not have direct contacts to organizations that own these products.
|
|
|
|
Depending on the third-party vendor's requirements, you might need to add a registered trademark symbol to all of the vendor's product names or only on the first occurence of referencing the product name in an assembly, a module, or a document.
|
|
|
|
Choose any of the following sources for clarification on using the symbol for a specific third-party vendor product name:
|
|
|
|
* Visit the third-party vendor's website and contact them directly.
|
|
* Contact internal Red Hat product teams or integrated third-party vendor teams.
|
|
* Contact the Red Hat Legal team. Only consider this option when the other two options did not provide clear context for your query.
|
|
|
|
[IMPORTANT]
|
|
====
|
|
Do not use Asciidoctor character replacement substitutions, which rely on a Unicode code point such as _®_, to set the registered symbol in an Asciidoc file. Instead use _(R)_ beside the product name. For example, `IBM(R) LinuxONE`.
|
|
|
|
Do not apply any superscript, such as `(R)`, or subscript formatting to module or assembly headings.
|
|
====
|
|
|
|
For more information about contacting the Red Hat's Legal team, see link:https://source.redhat.com/departments/legal/redhatintellectualproperty/trademarks/trademarks_and_domain_names_wiki/copyright_notices_and_trademark_legends[Copyright Notices and Trademark Legends] on the The Source.
|
|
|
|
//CANARY
|
|
[id="conditional-content"]
|
|
== Conditional content
|
|
|
|
You can use ifdef and ifeval statements to control the way content displays in different distributions and assemblies.
|
|
|
|
NOTE: You can nest conditional statements that involve distribution and assembly context, but you must ensure that you close the if statements correctly.
|
|
|
|
Because we maintain separate branches for each OpenShift Container Platform version, do not use if statements that are based on product version to vary content.
|
|
|
|
[id="conditionals-for-distributions"]
|
|
=== Conditionals for distributions
|
|
|
|
Use ifdef and ifndef statements to control content based on distribution, as described in the previous section. For example, the following example renders differently in (`openshift-origin`) and OpenShift Container Platform (`openshift-enterprise`):
|
|
|
|
----
|
|
\ifdef::openshift-origin[]
|
|
You can link:https://www.keycloak.org/docs/latest/server_admin/index.html#openshift[configure a Keycloak] server as an OpenID
|
|
Connect identity provider for {product-title}.
|
|
\endif::[]
|
|
|
|
\ifdef::openshift-enterprise[]
|
|
You can
|
|
link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/[configure Red Hat Single Sign-On]
|
|
as an OpenID Connect identity provider for {product-title}.
|
|
\endif::[]
|
|
----
|
|
|
|
In OKD, this section renders as the following text:
|
|
|
|
> You can link:https://www.keycloak.org/docs/latest/server_admin/index.html#openshift[configure a Keycloak] server as an OpenID
|
|
Connect identity provider for OKD.
|
|
|
|
In OpenShift Container Platform, this section renders as the following text:
|
|
|
|
> You can
|
|
link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/[configure Red Hat Single Sign-On]
|
|
as an OpenID Connect identity provider for OpenShift Container Platform.
|
|
|
|
|
|
[id="conditionals-for-assemblies"]
|
|
=== Conditionals for different assemblies
|
|
|
|
Use a combination of ifdef and ifeval statements to control content that needs to vary between assemblies. These conditional statements rely on a combination of the context attribute for each assembly and specific temporary attributes within each module to control content.
|
|
|
|
The following sample shows a simple example. In the assembly that contains the `context` attribute `updating-restricted-network-cluster`, an extra paragraph is displayed.
|
|
|
|
----
|
|
\ifeval::["{context}" == "updating-restricted-network-cluster"]
|
|
:restricted:
|
|
\endif::[]
|
|
|
|
...
|
|
|
|
\ifdef::restricted[]
|
|
If you are upgrading a cluster in a restricted network, install the `oc` version that you plan to upgrade to.
|
|
\endif::restricted[]
|
|
|
|
...
|
|
|
|
\ifeval::["{context}" == "updating-restricted-network-cluster"]
|
|
:!restricted:
|
|
\endif::[]
|
|
----
|
|
|
|
Note that you must set and unset each temporary attribute that you introduce to an assembly. Use the temporary attributes in the applicable ifdef and ifndef statements to vary text between the assemblies. The preceeding example uses `restricted` as the temporary attribute to display an additional paragraph for the assembly with the `updating-restricted-network-cluster` context attribute.
|
|
|
|
[id="do-not-use-sensitive-information-in-docs"]
|
|
== Ensuring that you do not include sensitive information
|
|
|
|
If you use sample code that you get from Engineering or QE team members, review the code for potentially sensitive data from customer or test environments.
|
|
Do not include test or customer data in any field or comment in the YAML.
|
|
|
|
Examples of sensitive information from customer or test environments can include:
|
|
|
|
Node names::
|
|
For example, internal company or customer server names.
|
|
See <<node-names>> for more information.
|
|
|
|
IP addresses::
|
|
Replace all public IP addresses with generic IP addresses.
|
|
See <<ip-addresses>> for more information.
|
|
|
|
MAC addresses::
|
|
Ensure that any MAC addresses that you include in source example are generic and do not identify real machines.
|
|
See <<mac-addresses>> for more information.
|
|
|
|
Sensitive Red Hat, customer, or partner information::
|
|
Remove or rework text or comments that inadvertently describe sensitive Red Hat, customer, or partner data, or names new or un-released features or products.
|
|
See <<sensitive-or-unreleased-information>> for more information.
|
|
|
|
[id="node-names"]
|
|
=== Node names
|
|
|
|
Do not use internal company server names in commands or example output. Provide generic OpenShift Container Platform node name examples that are not provider-specific, unless required. Where possible, use the example.com domain name when providing fully qualified domain names (FQDNs).
|
|
|
|
The following table includes example OpenShift Container Platform 4 node names and their corresponding role types:
|
|
|
|
[options="header"]
|
|
|===
|
|
|
|
|Node name |Role type
|
|
|
|
|*node-1.example.com*
|
|
.3+.^|You can use this format for nodes that do not need role-specific node names.
|
|
|
|
|*node-2.example.com*
|
|
|
|
|*node-3.example.com*
|
|
|
|
|*control-plane-1.example.com*
|
|
.3+.^|You can use this format if you need to describe the control plane role type within a node name.
|
|
|
|
|*control-plane-2.example.com*
|
|
|
|
|*control-plane-3.example.com*
|
|
|
|
|*compute-1.example.com*
|
|
.2+.^|You can use this format if you need to describe the compute node role type within a node name.
|
|
|
|
|*compute-2.example.com*
|
|
|
|
|*bootstrap.example.com*
|
|
|You can use this format if you need to describe the bootstrap node role type within a node name.
|
|
|===
|
|
|
|
This example lists the status of cluster nodes that use the node name formatting guidelines:
|
|
|
|
....
|
|
[source,terminal]
|
|
----
|
|
$ oc get nodes
|
|
----
|
|
+
|
|
.Example output
|
|
[source,terminal]
|
|
----
|
|
NAME STATUS ROLES AGE VERSION
|
|
compute-1.example.com Ready worker 33m v1.19.0+9f84db3
|
|
control-plane-1.example.com Ready master 41m v1.19.0+9f84db3
|
|
control-plane-2.example.com Ready master 45m v1.19.0+9f84db3
|
|
compute-2.example.com Ready worker 38m v1.19.0+9f84db3
|
|
compute-3.example.com Ready worker 33m v1.19.0+9f84db3
|
|
control-plane-3.example.com Ready master 41m v1.19.0+9f84db3
|
|
----
|
|
....
|
|
|
|
[NOTE]
|
|
====
|
|
Some provider-formatted hostnames include IPv4 addresses. An OpenShift Container Platform node name typically reflects the hostname of a node. If node names in your output need to be provider-specific and require this format, use private IPv4 addresses. For example, you could use `ip-10-0-48-9.example.com` as a node name that includes a private IPv4 address.
|
|
====
|
|
|
|
[id="ip-addresses"]
|
|
=== IP addresses
|
|
|
|
You may include IPv4 addresses from test clusters in examples in the documentation, provided that they are private. Private IPv4 addresses fall into one of the following ranges:
|
|
|
|
* 10.0.0.0 to 10.255.255.255 (class A address block 10.0.0.0/8)
|
|
* 172.16.0.0 to 172.31.255.255 (class B address block 172.16.0.0/12)
|
|
* 192.168.0.0 to 192.168.255.255 (class C address block 192.168.0.0/16)
|
|
|
|
Replace all public IP addresses with an address from the following blocks. These address blocks are reserved for documentation:
|
|
|
|
* 192.0.2.0 to 192.0.2.255 (TEST-NET-1 address block 192.0.2.0/24)
|
|
* 198.51.100.0 to 198.51.100.255 (TEST-NET-2 address block 198.51.100.0/24)
|
|
* 203.0.113.0 to 203.0.113.255 (TEST-NET-3 address block 203.0.113.0/24)
|
|
|
|
[NOTE]
|
|
====
|
|
There might be advanced networking examples that require specific IP addresses, or cloud provider-specific examples that require a public IP address. Contact a subject matter expert if you need assistance with replacing IP addresses.
|
|
====
|
|
|
|
[id="mac-addresses"]
|
|
=== MAC addresses
|
|
|
|
Ensure that any MAC addresses that you include in source example are generic and do not identify real hosts.
|
|
|
|
[id="sensitive-or-unreleased-information"]
|
|
=== Sensitive or customer-identifying data
|
|
|
|
Ensure that you do not include text or comments that inadvertently describes sensitive Red Hat, customer, or partner data.
|
|
|
|
Possible sources of customer-identifying data includes:
|
|
|
|
* Unreleased product names or project code words
|
|
* Customer and partner names
|
|
* Code comments
|
|
* Example YAML CR snippets
|
|
* Sample application code
|
|
* Logs
|
|
* Configuration files
|
|
* Command output
|
|
* Network or architecture diagrams
|
|
* Network packet captures
|
|
* Package version numbers
|
|
* Heap dumps
|
|
|
|
Where possible, replace specific details with generic examples.
|
|
|
|
[NOTE]
|
|
====
|
|
There might be advanced examples that require specific details, or multipart examples that require specific names to make sense.
|
|
If you have any doubt about what you are documenting, contact a subject matter expert or team lead.
|
|
====
|
|
|
|
[id="links-conditionals-assemblies"]
|
|
== Links, hyperlinks, and cross references
|
|
Links can be used to cross-reference internal assemblies or send readers to external information resources for further reading.
|
|
|
|
In OpenShift Container Platform docs:
|
|
|
|
* All links to internal content is created by using an `xref`, and each `xref` **must have an anchor ID**.
|
|
* Only use `xref` in assemblies, not in modules or snippets.
|
|
* All links to external websites are created by using the `link` attribute.
|
|
* Links between different distributions, or _distros_, such as from ROSA to OpenShift Container Platform, are external links and not cross-references. These external links use `link` instead of `xref` and must be in distro-specific files or a conditionalized state to apply to the relevant distros.
|
|
|
|
[IMPORTANT]
|
|
====
|
|
Do not split link paths across lines when wrapping text. This will cause issues with the documentation builds.
|
|
====
|
|
|
|
[id="lead-in-link-sentences"]
|
|
=== Lead-in link sentences
|
|
|
|
Using a lead-in link sentence that adheres to guidelines maintains consistency across OpenShift Container Platform documentation.
|
|
|
|
==== Lead-in link sentence style for non-xref situations
|
|
|
|
For situations where you cannot use the `xref` attribute, such as referencing a module within a module, ensure that you adhere to the following guidance for lead-in link sentences.
|
|
|
|
* Use the following format when pointing to a section in the same document:
|
|
+
|
|
[source,text,subs="+quotes"]
|
|
----
|
|
For more information, see "<section_name>".
|
|
----
|
|
|
|
* Wrap the `<section_name>` string in quotation marks. The section name can be the title of a module or an assembly.
|
|
|
|
* Do not state "in the Additional resources section" or other variants. Mentioning the `<section_name>` is enough to prompt a documentation user to find the section in the same document.
|
|
|
|
==== Lead-in link sentence style for the xref attribute
|
|
|
|
For situations where you can use the `xref` attribute, adhere to the following guidance:
|
|
|
|
* When pointing to a section (module) that exists in the same document (assembly), create an _Additional resources_ section in the assembly file and then place the `xref` as a bulleted item under the _Additional resources_ section. For example:
|
|
+
|
|
[source,text]
|
|
----
|
|
[role="_additional-resources"]
|
|
.Additional resources
|
|
* xref:../../../installing/installing_vsphere/installation-config-parameters-vsphere.adoc#installation-config-parameters-vsphere[Installation configuration parameters]
|
|
----
|
|
|
|
* When pointing to a link in a section (module) that exists in another OpenShift Container Platform document (assembly), use the following format:
|
|
+
|
|
[source,text]
|
|
----
|
|
For more information on <topic>, see xref:<path_to_file>["<section_name>"] in _<document_name>_.
|
|
----
|
|
|
|
Note the quotation marks around `<section_name>` and the italics around `<document_name>`.
|
|
|
|
For more information about using `xref`, see xref:links-conditionals-assemblies[Links, hyperlinks, and cross references].
|
|
|
|
==== Lead-in link sentence style for the link attribute
|
|
|
|
For situations where you can use the `link` attribute, adhere to the following guidance:
|
|
|
|
* When pointing to a link that exists external to Red Hat's customer portal documentation, add the `link` attribute, and use the `<document_heading_name> (<document_source>)` format. For example:
|
|
+
|
|
[source,text]
|
|
----
|
|
See link:https://aws.amazon.com/about-aws/global-infrastructure/localzones/features/[AWS Local Zones features] (AWS documentation).
|
|
----
|
|
|
|
[NOTE]
|
|
====
|
|
Certain Red Hat resources, such as Knowledgebase articles, exist in a separate server location to Red Hat customer portal documentation. For these resources, use the `link` attribute format.
|
|
|
|
For more information, see link:https://redhat-documentation.github.io/supplementary-style-guide/#rh-kb-links[Links to Red Hat Knowledgebase articles] (Red Hat supplementary style guide for product documentation).
|
|
====
|
|
|
|
For more information about using `link`, see xref:links-conditionals-assemblies[Links, hyperlinks, and cross references].
|
|
|
|
=== Example URLs
|
|
To provide an example URL path that you do not want to render as a hyperlink, use this format:
|
|
|
|
....
|
|
`\https://www.example.com`
|
|
....
|
|
|
|
=== Internal cross-references
|
|
|
|
Use the relative file path (from the file you are editing to the file you are linking to), even if you are linking to the same directory that you are writing in. This makes search and replace operations to fix broken links much easier.
|
|
|
|
For example, if you are writing in `architecture/core_concepts/deployments.adoc` and you want to link to `architecture/core_concepts/routes.adoc`, then you must include the path back to the first level of the assembly directory:
|
|
|
|
----
|
|
xref:../../architecture/networking/routes.adoc#architecture-core-concepts-routes
|
|
----
|
|
|
|
[NOTE]
|
|
====
|
|
In OpenShift docs, you can only use `xref` in assemblies, not in modules.
|
|
====
|
|
|
|
.Markup example of cross-referencing
|
|
----
|
|
For more information, see xref:../dev_guide/application_lifecycle/new_app.adoc#dev-guide-new-app[Creating an application].
|
|
|
|
Rollbacks can be performed using the REST API or the xref:../cli_reference/openshift_cli/get_started_cli.adoc#installing-openshift-cli[OpenShift CLI].
|
|
----
|
|
|
|
.Rendered output of cross-referencing
|
|
> For more information, see xref:../dev_guide/application_lifecycle/new_app.adoc#dev-guide-new-app[Creating an application].
|
|
>
|
|
> Rollbacks can be performed using the REST API or the xref:../cli_reference/openshift_cli/get_started_cli.adoc#installing-openshift-cli[OpenShift CLI].
|
|
|
|
=== Links to external websites
|
|
|
|
If you want to link to a different website, use:
|
|
|
|
----
|
|
link:http://othersite.com/otherpath[friendly reference text]
|
|
----
|
|
|
|
IMPORTANT: You must use `link:` before the start of the URL.
|
|
|
|
IMPORTANT: You cannot link to a repository that is hosted on www.github.com. An exception to this rule is when autogenerated API reference content contains a link to www.github.com.
|
|
|
|
TIP: If you want to build a link from a URL _without_ changing the text from the actual URL, just print the URL without adding a `[friendly text]` block at the end; it will automatically be rendered as a link.
|
|
|
|
=== Links to internal content
|
|
There are two scenarios for linking to other assemblies:
|
|
|
|
1. Link to another file that exists in the same directory.
|
|
2. Link to another file that exists in a separate directory.
|
|
|
|
The following examples use the example directory structure shown here:
|
|
....
|
|
/
|
|
/foo
|
|
/foo/bar.adoc
|
|
/baz
|
|
/baz/zig.adoc
|
|
/baz/zag.adoc
|
|
....
|
|
|
|
*Link to assembly in same directory*
|
|
|
|
----
|
|
xref:<filename>#anchor-id[friendly title]
|
|
----
|
|
|
|
You must use the `.adoc` file extension. The document processor will correctly link this to the resulting HTML file.
|
|
|
|
For example, using the above syntax, if you are working on `zig.adoc` and want to link to `zag.adoc`, do it this way:
|
|
|
|
----
|
|
xref:../zag.adoc#baz-zag[comment]
|
|
----
|
|
|
|
where `baz-zag` is the anchor ID at the top of the file `zag.adoc`.
|
|
|
|
*Link to assembly in different directory*
|
|
|
|
----
|
|
xref:../dir/<filename>.adoc#anchor-id[friendly title]
|
|
----
|
|
|
|
For example, if you are working on `bar.adoc` and you want to link to `zig.adoc`, do it this way:
|
|
|
|
----
|
|
For more information, see the xref:../baz/zig.adoc#baz-zig[ZIG manual].
|
|
----
|
|
|
|
[NOTE]
|
|
====
|
|
You must use the `.adoc` extension in order for the link to work correctly and you must specify an anchor ID.
|
|
====
|
|
|
|
== Embedding an external file
|
|
|
|
You can embed content hosted outside the link:https://github.com/openshift/openshift-docs[openshift-docs]
|
|
GitHub repository by using the `include` directive to target the URI of a raw
|
|
file. This is helpful for cases where content frequently changes; you embed the raw
|
|
file and the content auto-updates based on the changes made to the content on its
|
|
host site.
|
|
|
|
[IMPORTANT]
|
|
====
|
|
You are restricted to only embed files from GitHub repositories managed by the
|
|
`openshift` or `openshift-kni` GitHub user. You must also prefix your external file URI with `https`.
|
|
URIs beginning with `http` are forbidden for security reasons and will fail the
|
|
documentation build.
|
|
====
|
|
|
|
For example, if you want to embed the link:https://github.com/openshift/installer/blob/release-4.8/upi/azure/01_vnet.json[01_vnet.json] template, include the URI of its raw file version like this:
|
|
|
|
```
|
|
.`01_vnet.json` ARM template
|
|
[source,json]
|
|
----
|
|
\include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/azure/01_vnet.json[]
|
|
----
|
|
```
|
|
|
|
[NOTE]
|
|
====
|
|
Embedding external files is restricted for files that change frequently, like templates. You must ensure that embedded files are QE verified before they are updated on their host site.
|
|
====
|
|
|
|
[NOTE]
|
|
====
|
|
You must get approval from the Engineering, QE, and Docs teams before embedding an external file.
|
|
====
|
|
|
|
== Embedding a local YAML file
|
|
|
|
You can embed local YAML files in AsciiDoc modules.
|
|
Consider embedding a local YAML file when you have a complete and valid YAML file that you want to use.
|
|
This is useful when you want to include a complete YAML CR in the docs.
|
|
The YAML file that you include must be a local file maintained in the link:https://github.com/openshift/openshift-docs[openshift-docs] GitHub repository.
|
|
Use the `include` directive to target the local file.
|
|
|
|
To use a local YAML file, add it to the `snippets/` folder, and include it in your module. For example:
|
|
|
|
[source,yaml]
|
|
----
|
|
\include::snippets/install-config.yaml[]
|
|
----
|
|
|
|
[NOTE]
|
|
====
|
|
Do not include link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-lines/[lines by content ranges]. This approach can lead to content errors when the included file is subsequently updated.
|
|
====
|
|
|
|
[IMPORTANT]
|
|
====
|
|
If the YAML file you want to include is from a GitHub repository that is managed by the `openshift` GitHub user, link to the file directly rather than copying the file to the `/openshift-docs` folder.
|
|
====
|
|
|
|
[discrete]
|
|
=== Using AsciiDoc callouts in the YAML
|
|
|
|
You can use AsciiDoc callouts in the YAML file.
|
|
Comment out the callout in the YAML file to ensure that file can still be parsed as valid YAML.
|
|
Asciidoctor recognises the commented callout and renders it correctly in the output.
|
|
For example:
|
|
|
|
`apiVersion: v1 # <1>`
|
|
|
|
[discrete]
|
|
=== Version and upgrade implications
|
|
|
|
Carefully consider the version and upgrade implications of including the local YAML file in your content. Including a local YAML file can increase the maintenance overhead for the content.
|
|
If you have a doubt, talk to your content strategist or docs team lead.
|
|
|
|
[discrete]
|
|
=== Validating the local YAML file
|
|
|
|
Before you include the YAML file, use a YAML linter or the `oc` CLI to verify that the YAML is valid.
|
|
For example, to validate the `snippets/SiteConfig.yaml` file using `oc`, log in to a cluster and run the following command from a terminal opened in the `openshift-docs/` folder:
|
|
|
|
[source,terminal]
|
|
----
|
|
$ oc apply -f snippets/SiteConfig.yaml --dry-run=client
|
|
----
|
|
|
|
.Example output
|
|
[source,terminal]
|
|
----
|
|
siteconfig.ran.openshift.io/example-sno created (dry run)
|
|
----
|
|
|
|
Running `oc` with the `--dry-run=client` switch does not succeed with an invalid YAML file.
|
|
|
|
== Indicating Technology Preview features
|
|
|
|
To indicate that a feature is in Technology Preview, include the `snippets/technology-preview.adoc` file in the feature's assembly or module to keep the supportability wording consistent across Technology Preview features. Provide a value for the `:FeatureName:` variable before you include this module.
|
|
|
|
[source,text]
|
|
----
|
|
:FeatureName: The XYZ plug-in
|
|
\include::snippets/technology-preview.adoc[]
|
|
----
|
|
|
|
== Indicating deprecated features
|
|
|
|
To indicate that a feature is deprecated, include the `modules/deprecated-feature.adoc` file in the feature's assembly, or to each relevant assembly such as for a deprecated Operator, to keep the supportability wording consistent across deprecated features. Provide a value for the `:FeatureName:` variable before you include this module.
|
|
|
|
For more information on how this is applied, see link:https://github.com/openshift/openshift-docs/pull/31776/files[this example PR].
|
|
|
|
== Verification of your content
|
|
All documentation changes that update or add technical content must be verified by a QE team associate before merging. This QE verification process includes executing all procedures, confirming expected results, and confirming the accuracy of conceptual and reference content. The only exceptions are for typo-level changes, formatting-only changes, and other negotiated documentation sets and distributions.
|
|
|
|
If a documentation change is due to a Bugzilla bug or Jira issue, the bug/issue should be put on ON_QA when you have a PR ready. After QE approval is given (either in the bug/issue or in the PR), the QE associate should move the bug/issue status to VERIFIED, at which point the associated PR can be merged. It is also ok for the assigned writer to change the status of the bug/issue to VERIFIED if approval for the changes has been provided in another forum (slack, PR, or email). The writer should indicate that the QE team approved the change as a comment in the bug/issue.
|
|
|
|
== Images
|
|
|
|
=== Image format
|
|
|
|
Use `*.png` format images.
|
|
|
|
=== Block images
|
|
|
|
To include a block image (an image on its own line):
|
|
|
|
1. Put the image file in the `images` folder.
|
|
+
|
|
Ensure that the folder containing your assembly contains an `images` symbolic link to the top-level `images/` directory, otherwise the image will not be found when building the docs.
|
|
|
|
2. In the `.adoc` content, use this format to link to the image:
|
|
+
|
|
----
|
|
image::<image_filename>[<alt_text>]
|
|
----
|
|
+
|
|
Note the double `::` instead of a single `:`, as seen in inline image usage.
|
|
You only have to specify `<image_filename>` itself and not the full file path;
|
|
the build mechanism automatically expands this appropriately.
|
|
|
|
=== Inline images (icons)
|
|
|
|
Inline images can be used to indicate graphic items in the web console, such as
|
|
buttons or menu icons.
|
|
|
|
==== Inserting reusable images inline
|
|
|
|
To simplify reuse, the following common SVGs (the OpenShift web console uses the
|
|
Font Awesome icon set) have already been added to the `images` folder with a
|
|
user-defined entity added to the `common-attributes.adoc` module:
|
|
|
|
|===
|
|
|Icon |Entity |Alt text |File name
|
|
|
|
|Kebab
|
|
|`:kebab:`
|
|
|Options menu
|
|
|`ellipsis-v.svg`
|
|
|
|
|===
|
|
|
|
When using inline, include the image after the UI element name. For example:
|
|
|
|
----
|
|
Click the Options menu {kebab}.
|
|
----
|
|
|
|
==== Inserting images inline without reuse
|
|
|
|
If you are inserting an image that is not part of the `common-attributes.adoc`
|
|
module, then include the image using this formatting:
|
|
|
|
----
|
|
image:<image_filename>[title="<alt_text>"]
|
|
----
|
|
|
|
Note the single `:` instead of a double `::`, as seen in block image usage.
|
|
|
|
For example:
|
|
|
|
----
|
|
image:manage-columns.png[title="Manage Columns icon"]
|
|
----
|
|
|
|
== Formatting
|
|
|
|
For all of the system blocks including table delimiters, use four characters. For example:
|
|
|
|
....
|
|
|=== for tables
|
|
---- for code blocks
|
|
....
|
|
|
|
[NOTE]
|
|
====
|
|
You can use backticks or other markup in the title for a block, such as a code block `.Example` or a table `.Description` title.
|
|
====
|
|
|
|
=== Code blocks, command syntax, and example output
|
|
|
|
Code blocks are generally used to show examples of command syntax, example screen output, and configuration files.
|
|
|
|
//redundant with 1080
|
|
The main distinction between showing command syntax and a command example is that a command syntax shows readers how to use the command without real values. An example command, however, shows the command with actual values with an example output of that command, where applicable.
|
|
|
|
[[use-source-terminal]]
|
|
==== Source tags for terminal commands and output
|
|
* Use `[source,terminal]` for `oc` commands or any terminal commands to enable syntax highlighting. If you are also showing a code block for the output of the command, use `[source,terminal]` for that code block as well. Separate a command and its related example output into individual code blocks. See <<single-command-per-code-block>>.
|
|
+
|
|
For example:
|
|
+
|
|
....
|
|
In the following example, the `oc get` operation returns a complete list of services that are currently defined:
|
|
|
|
[source,terminal]
|
|
----
|
|
$ oc get se
|
|
----
|
|
|
|
.Example output
|
|
[source,terminal]
|
|
----
|
|
NAME LABELS SELECTOR IP PORT
|
|
kubernetes component=apiserver,provider=kubernetes <none> 172.30.17.96 443
|
|
kubernetes-ro component=apiserver,provider=kubernetes <none> 172.30.17.77 80
|
|
docker-registry <none> name=registrypod 172.30.17.158 5001
|
|
----
|
|
....
|
|
+
|
|
This renders as:
|
|
+
|
|
> In the following example, the `oc get` operation returns a complete list of services that are currently defined:
|
|
>
|
|
> ----
|
|
> $ oc get se
|
|
> ----
|
|
>
|
|
> .Example output
|
|
> ----
|
|
> NAME LABELS SELECTOR IP PORT
|
|
> kubernetes component=apiserver,provider=kubernetes <none> 172.30.17.96 443
|
|
> kubernetes-ro component=apiserver,provider=kubernetes <none> 172.30.17.77 80
|
|
> docker-registry <none> name=registrypod 172.30.17.158 5001
|
|
> ----
|
|
|
|
* Any `[source]` metadata must go on the line directly before the code block. Also, do not insert a space in between the `[source]` tag and the metadata.
|
|
//Context: https://github.com/openshift/openshift-docs/pull/64373
|
|
+
|
|
For example:
|
|
+
|
|
....
|
|
|
|
[source,terminal]
|
|
----
|
|
$ oc get se
|
|
----
|
|
|
|
[source,yaml]
|
|
----
|
|
apiVersion: config.openshift.io/v1
|
|
kind: Scheduler
|
|
metadata:
|
|
name: cluster
|
|
# ...
|
|
spec:
|
|
defaultNodeSelector: node-role.kubernetes.io/app=
|
|
# ...
|
|
----
|
|
....
|
|
|
|
* For Bash "here" documents use `[source,terminal]`, such as the following example:
|
|
+
|
|
....
|
|
[source,terminal]
|
|
----
|
|
$ cat <<EOF| oc create -f -
|
|
apiVersion: v1
|
|
kind: Pod
|
|
metadata:
|
|
name: mlistener
|
|
labels:
|
|
app: multicast-verify
|
|
EOF
|
|
----
|
|
....
|
|
+
|
|
[NOTE]
|
|
====
|
|
For bash scripts, use `[source,bash]`. For example:
|
|
[source,bash]
|
|
----
|
|
#!/bin/bash
|
|
|
|
# optional argument handling
|
|
if [[ "$1" == "config" ]]
|
|
then
|
|
echo $KUBECONFIG
|
|
exit 0
|
|
fi
|
|
|
|
echo "I am a plugin named kubectl-test"
|
|
----
|
|
====
|
|
|
|
The following guidelines go into more detail about specific requirements and recommendations when using code blocks:
|
|
|
|
[[step-with-command]]
|
|
==== Procedure step that introduces a command
|
|
If a step in a procedure is to run a command, make sure that the step text includes an explicit instruction to "run" or "enter" the command. In most cases, use one of the following patterns to introduce the code block:
|
|
|
|
** <Step description> by running the following command:
|
|
** <Step description> by entering the following command:
|
|
** <Step description>, run the following command:
|
|
** <Step description>, enter the following command:
|
|
|
|
[[no-markup-codeblock]]
|
|
==== No markup in code blocks
|
|
Do NOT use any markup in code blocks; code blocks generally do not accept any markup.
|
|
|
|
[[empty-line-before-codeblock]]
|
|
==== Empty line before code blocks
|
|
For all code blocks, you must include an empty line above a code block (unless that line is introducing block metadata, such as `[source,terminal]` for syntax highlighting).
|
|
|
|
Acceptable:
|
|
|
|
....
|
|
Lorem ipsum
|
|
|
|
----
|
|
$ lorem.sh
|
|
----
|
|
....
|
|
|
|
Not acceptable:
|
|
|
|
....
|
|
Lorem ipsum
|
|
----
|
|
$ lorem.sh
|
|
----
|
|
....
|
|
|
|
Without the line spaces, the content is likely to be not parsed correctly.
|
|
|
|
[[source-tags-for-programming-language]]
|
|
==== Source tags for programming languages
|
|
Use source tags for the programming language used in the code block to enable syntax highlighting. For example:
|
|
|
|
** `[source,yaml]`
|
|
** `[source,go]`
|
|
** `[source,javascript]`
|
|
** `[source,jsx]`
|
|
** `[source,bash]`
|
|
|
|
[[single-command-per-code-block]]
|
|
==== Single command per code block
|
|
Do not use more than one command per code block.
|
|
|
|
When commands are bunched together, the copy to clipboard functionality might not break the lines up correctly. Using single command per code block makes it copy-and-paste friendly.
|
|
|
|
For example, the following must be split up into three separate code blocks:
|
|
|
|
....
|
|
To create templates you can modify, run the following commands:
|
|
|
|
[source,terminal]
|
|
----
|
|
$ oc adm create-login-template > login.html
|
|
----
|
|
|
|
[source,terminal]
|
|
----
|
|
$ oc adm create-provider-selection-template > providers.html
|
|
----
|
|
|
|
[source,terminal]
|
|
----
|
|
$ oc adm create-error-template > errors.html
|
|
----
|
|
....
|
|
|
|
[[command-syntax-replaceable-values]]
|
|
==== Command syntax for replaceable values
|
|
To mark up command syntax, use the code block and wrap any replaceable values in angle brackets (`<>`) with the required command parameter, using underscores (`_`) between words as necessary for legibility.
|
|
|
|
[IMPORTANT]
|
|
====
|
|
In core OpenShift Container Platform documentation, do not italicize user-replaced values. This guideline is an exception to the link:https://redhat-documentation.github.io/supplementary-style-guide/#user-replaced-values[_Red Hat supplementary style guide for product documentation_].
|
|
|
|
Red Hat build of MicroShift documentation follows the SSG and italicizes user-replaced values.
|
|
====
|
|
|
|
For example:
|
|
|
|
....
|
|
To view a list of objects for the specified object type, enter the following command:
|
|
|
|
[source,terminal]
|
|
----
|
|
$ oc get <object_type> <object_id>
|
|
----
|
|
....
|
|
|
|
This renders as:
|
|
|
|
--
|
|
> To view a list of objects for the specified object type, enter the following command:
|
|
>
|
|
> ----
|
|
> $ oc get <object_type> <object_id>
|
|
> ----
|
|
--
|
|
|
|
NOTE: Avoid using full command syntax inline with sentences.
|
|
|
|
[[resource-names-oc-commands]]
|
|
==== Resource names in oc commands
|
|
* When you specify link:https://kubernetes.io/docs/reference/kubectl/#resource-types[resource names] in `oc` commands, use the full name of the resource type by default. You can use the abbreviation of the resource type name if it improves readability, such as with very long commands, or to be consistent with existing content in the same assembly.
|
|
+
|
|
For example, use `namespaces` instead of `ns` and `poddisruptionbudgets` instead of `pdb`.
|
|
|
|
* When referring to a path to a location that the user has selected or created, treat the part of the path that the user chose as a replaceable value. For example:
|
|
+
|
|
....
|
|
Create a secret that contains the certificate and key in the `openshift-config` namespace:
|
|
|
|
[source,terminal]
|
|
----
|
|
$ oc create secret tls <certificate> --cert=<path_to_certificate>/cert.crt --key=<path_to_key>/cert.key -n openshift-config
|
|
----
|
|
....
|
|
+
|
|
This renders as:
|
|
+
|
|
--
|
|
> Create a secret that contains the certificate and key in the `openshift-config` namespace:
|
|
>
|
|
> ----
|
|
> $ oc create secret tls <certificate> --cert=<path_to_certificate>/cert.crt --key=<path_to_key>/cert.key -n openshift-config
|
|
> ----
|
|
--
|
|
+
|
|
The following example shows a more complex use of user-chosen elements and prescriptive placement:
|
|
+
|
|
....
|
|
<resource_group_name>/providers/Microsoft.Compute/diskEncryptionSets/<disk_encryption_set_name>
|
|
....
|
|
|
|
[[backslash-for-long-code-line]]
|
|
==== Backslash for long lines of code
|
|
For long lines of code that you want to break up among multiple lines, use a backslash to show the line break and indent all lines under the first with two spaces. For example:
|
|
|
|
....
|
|
[source,terminal]
|
|
----
|
|
$ oc get endpoints --all-namespaces --template \
|
|
'{{ range .items }}{{ .metadata.namespace }}:{{ .metadata.name }} \
|
|
{{ range .subsets }}{{ range .addresses }}{{ .ip }} \
|
|
{{ end }}{{ end }}{{ "\n" }}{{ end }}' | awk '/ 172\.30\./ { print $1 }'
|
|
----
|
|
....
|
|
|
|
[[callouts-in-codeblocks]]
|
|
==== Callouts in code blocks
|
|
* If you must provide additional information on what a line of a code block represents, use callouts (`<1>`, `<2>`, etc.) to provide that information.
|
|
+
|
|
Use this format when embedding callouts into the code block:
|
|
+
|
|
[subs=-callouts]
|
|
....
|
|
----
|
|
code example 1 <1>
|
|
code example 2 <2>
|
|
----
|
|
<1> A note about the first example value.
|
|
<2> A note about the second example value.
|
|
....
|
|
|
|
* If your command contains multiple lines and uses callout annotations, you must comment out the callout(s) in the codeblock, as shown in the following example:
|
|
+
|
|
|
|
To scale based on the percent of CPU utilization, create a `HorizontalPodAutoscaler` object for an existing object:
|
|
+
|
|
[subs=-callouts]
|
|
....
|
|
[source,terminal]
|
|
----
|
|
$ oc autoscale <object_type>/<name> \// <1>
|
|
--min <number> \// <2>
|
|
--max <number> \// <3>
|
|
--cpu-percent=<percent> <4>
|
|
----
|
|
<1> Specify the type and name of the object to autoscale.
|
|
<2> Optional: Specify the minimum number of replicas when scaling down.
|
|
<3> Specify the maximum number of replicas when scaling up.
|
|
<4> Specify the target average CPU utilization over all the pods, represented as a percent of requested CPU.
|
|
....
|
|
|
|
* If you must provide additional information on what a line of a code block represents and the use of callouts is impractical, you can use a description list to provide information about the variables in the code block. Using callouts might be impractical if a code block contains too many conditional statements to easily use numbered callouts or if the same note applies to multiple lines of the codeblock.
|
|
+
|
|
Be sure to introduce the description list with "where:" and start each variable description with "Specifies."
|
|
+
|
|
....
|
|
----
|
|
code <variable_1>
|
|
code <variable_2>
|
|
----
|
|
+
|
|
where:
|
|
|
|
<variable_1>:: Specifies the explanation of the first variable.
|
|
<variable_2>:: Specifies the explanation of the first variable.
|
|
....
|
|
+
|
|
For example:
|
|
+
|
|
....
|
|
[source,terminal]
|
|
----
|
|
$ oc annotate route <route_name> router.openshift.io/cookie_name="<cookie_name>"
|
|
----
|
|
+
|
|
where:
|
|
|
|
`<route_name>`:: Specifies the name of the route.
|
|
`<cookie_name>`:: Specifies the name for the cookie.
|
|
....
|
|
|
|
[[signs-symbols-in-codeblocks]]
|
|
==== Signs and symbols in code blocks
|
|
* If the user must run a command as root, use a number sign (`#`) at the start of the command instead of a dollar sign (`$`). For example:
|
|
+
|
|
----
|
|
# subscription-manager list
|
|
----
|
|
|
|
* For snippets or sections of a file, use an ellipsis (`...`) to show that the file continues before or after the quoted block. For YAML, use ('#...') instead.
|
|
+
|
|
----
|
|
apiVersion: v1
|
|
kind: Pod
|
|
metadata:
|
|
labels:
|
|
test: liveness
|
|
# ...
|
|
----
|
|
+
|
|
or
|
|
+
|
|
----
|
|
Name: ci-ln-iyhx092-f76d1-nvdfm-worker-b-wln2l
|
|
Roles: worker
|
|
...
|
|
Taints: node-role.kubernetes.io/infra:NoSchedule
|
|
...
|
|
----
|
|
+
|
|
Do not use `[...]`, `<snip>`, or any other variant.
|
|
|
|
[[jq-commands]]
|
|
==== Commands with jq
|
|
Do not use `jq` in commands (unless it is truly required), because this requires users to install the `jq` tool. Oftentimes, the same or similar result can be accomplished using `jsonpath` for `oc` commands.
|
|
|
|
For example, this command that uses `jq`:
|
|
|
|
----
|
|
$ oc get clusterversion -o json|jq ".items[0].spec"
|
|
----
|
|
|
|
can be updated to use `jsonpath` instead:
|
|
|
|
----
|
|
$ oc get clusterversion -o jsonpath='{.items[0].spec}{"\n"}'
|
|
----
|
|
|
|
=== YAML formatting for Kubernetes and OpenShift API objects
|
|
The following formatting guidelines apply to YAML manifests, but do not apply to the installation configuration YAML specified by `install-config.yaml`.
|
|
|
|
When possible, ensure that YAML is valid in a running cluster. You can validate YAML with `oc apply` with the following invocation:
|
|
|
|
----
|
|
$ oc apply -f test.yaml --dry-run=client
|
|
----
|
|
|
|
==== Required fields
|
|
|
|
- Include the `apiVersion` and `kind` so that a user always knows the context of the YAML.
|
|
- Include the full hierarchy to a deeply nested key.
|
|
- For objects that are in the global scope, such as for `config.openshift.io` API group, always include the `metadata.name` for the object, which is usually `cluster`.
|
|
|
|
.Example API object in the global scope
|
|
----
|
|
apiVersion: config.openshift.io/v1
|
|
kind: Scheduler
|
|
metadata:
|
|
name: cluster
|
|
# ...
|
|
spec:
|
|
defaultNodeSelector: node-role.kubernetes.io/app=
|
|
# ...
|
|
----
|
|
|
|
.Example deeply nested key with full context for `.ports` array
|
|
----
|
|
apiVersion: v1
|
|
kind: Pod
|
|
metadata:
|
|
name: pod1
|
|
namespace: default
|
|
spec:
|
|
containers:
|
|
- name: web
|
|
image: nginx
|
|
ports:
|
|
- name: web
|
|
containerPort: 80
|
|
protocol: TCP
|
|
----
|
|
|
|
==== YAML formatting
|
|
The following conventions govern the layout of YAML for API objects:
|
|
|
|
- Begin YAML at the beginning of the left margin.
|
|
- Use two-space indentation.
|
|
- Indent arrays at the same depth as the parent field.
|
|
- Include a space immediately after the colon for keys.
|
|
- Use block style for complex strings, such as embedded JSON or text blocks. You can enable block style by specifying `|` or `|-` after a field and indenting the field content by two spaces, such as in the following example:
|
|
+
|
|
----
|
|
fieldName: |-
|
|
This is a string.
|
|
And it can be on multiple lines.
|
|
----
|
|
- When truncating YAML, comment out the ellipsis (`# ...`) because three dots (`...`) in YAML is actually a link:https://yaml.org/spec/1.2.2/#22-structures[document end marker].
|
|
- Use three hyphens (`---`) to separate YAML definitions in a single YAML file.
|
|
|
|
.Example with array indentation flush with parent field
|
|
----
|
|
apiVersion: v1
|
|
kind: Pod
|
|
metadata:
|
|
name: pod1
|
|
labels:
|
|
- key1: val1
|
|
- key2: val2
|
|
spec:
|
|
# ...
|
|
----
|
|
|
|
.Example with block string for annotation
|
|
----
|
|
apiVersion: v1
|
|
kind: Pod
|
|
metadata:
|
|
name: pod1
|
|
annotations:
|
|
k8s.v1.cni.cncf.io/networks: |-
|
|
[
|
|
{
|
|
"name": "net"
|
|
}
|
|
]
|
|
spec:
|
|
# ...
|
|
----
|
|
|
|
=== Inline code or commands
|
|
Do NOT show full commands or command syntax inline within a sentence. The next section covers how to show commands and command syntax.
|
|
|
|
Only use case for inline commands would be general commands and operations, without replaceables and command options. In this case an inline command is marked up using the back ticks:
|
|
|
|
....
|
|
Use the `GET` operation to do x.
|
|
....
|
|
|
|
This renders as:
|
|
|
|
> Use the `GET` operation to do x.
|
|
|
|
=== System messages
|
|
|
|
System messages include error, warning, confirmation, and information messages that are presented to the user in places such as the GUI, CLI, or system logs.
|
|
|
|
If a message is short enough to include inline, enclose it in back ticks:
|
|
|
|
....
|
|
Previously, image builds and pushes would fail with the `error reading blob from source` error message because the builder logic would compute the contents of new layers twice.
|
|
....
|
|
|
|
This renders as:
|
|
|
|
> Previously, image builds and pushes would fail with the `error reading blob from source` error message because the builder logic would compute the contents of new layers twice.
|
|
|
|
If a message is too long to include inline, put it inside a code block with `[source,text]` metadata:
|
|
|
|
....
|
|
Previously, the AWS Terraform provider that the installation program used occasionally caused a race condition with the S3 bucket, and the cluster installation failed with the following error message:
|
|
|
|
[source,text]
|
|
----
|
|
When applying changes to module.bootstrap.aws_s3_bucket.ignition, provider level=error msg="\"aws\" produced an unexpected new value for was present, but now absent.
|
|
----
|
|
|
|
Now, the installation program uses different AWS Terraform provider code, which now robustly handles S3 eventual consistency, and the installer-provisioned AWS cluster installation does not fail with that error message.
|
|
....
|
|
|
|
This renders as:
|
|
|
|
> Previously, the AWS Terraform provider that the installation program used occasionally caused a race condition with the S3 bucket, and the cluster installation failed with the following error message:
|
|
>
|
|
> ----
|
|
> When applying changes to module.bootstrap.aws_s3_bucket.ignition, provider level=error msg="\"aws\" produced an unexpected new value for was present, but now absent.
|
|
> ----
|
|
>
|
|
> Now, the installation program uses different AWS Terraform provider code, which now robustly handles S3 eventual consistency, and the installer-provisioned AWS cluster installation does not fail with that error message.
|
|
|
|
NOTE: Always refer to a message with the type of message it is, followed by the word "message". For example, refer to an error message as an "error message", and not simply as an "error".
|
|
|
|
=== Lists
|
|
Lists are created as shown in this example:
|
|
|
|
....
|
|
. Item 1 (2 spaces between the period and the first character)
|
|
|
|
. Item 2
|
|
|
|
. Item 3
|
|
....
|
|
|
|
This renders as:
|
|
|
|
> . Item 1
|
|
> . Item 2
|
|
> . Item 3
|
|
|
|
If you must add any text, admonitions, or code blocks you have to add the continuous +, as shown in the example:
|
|
|
|
....
|
|
. Item 1
|
|
+
|
|
----
|
|
some code block
|
|
----
|
|
|
|
. Item 2
|
|
|
|
. Item 3
|
|
....
|
|
|
|
This renders as:
|
|
|
|
> . Item 1
|
|
> +
|
|
> ----
|
|
> some code block
|
|
> ----
|
|
> . Item 2
|
|
> . Item 3
|
|
|
|
=== Support matrix tables
|
|
|
|
In tables that indicate version support, feature inclusion, or similar with a simple single-character indicator, use a capital letter "X" (`X`) centered in the cell.
|
|
Other options, such as Unicode and emoji checkmarks, might lack screen reader support or require alt text.
|
|
|
|
=== Footnotes
|
|
|
|
Avoid footnotes when possible.
|
|
|
|
If you reference a footnote from only a single location, use the following syntax:
|
|
|
|
.Footnote
|
|
....
|
|
footnote:[This is the footnote text.]
|
|
....
|
|
|
|
If you reference a footnote from multiple locations, set an attribute with the footnote text. As a consequence, this will duplicate the footnote text at bottom of the page.
|
|
|
|
.Footnote with text set by an attribute
|
|
....
|
|
:note-text: This is a footnote.
|
|
|
|
This text has a footnote qualifier attached footnote:[{note-text}].
|
|
|
|
But this other text uses the same qualifier elsewhere footnote:[{note-text}].
|
|
....
|
|
|
|
Avoid using `footnoteref`.
|
|
|
|
[IMPORTANT]
|
|
====
|
|
The `footnoteref` directive is deprecated in asciidoctor and causes a build warning when `ascii_binder` is run.
|
|
====
|
|
|
|
.Footnote with reference
|
|
....
|
|
footnoteref:[ref-string, This is the footnote text.]
|
|
....
|
|
|
|
==== Alternative footnote styling in tables
|
|
|
|
For footnotes in tables, use the following syntax:
|
|
|
|
....
|
|
[cols="3",options="header"]
|
|
|===
|
|
|Header 1
|
|
|Header 2
|
|
|Header 3
|
|
|
|
|Item A ^[1]^
|
|
|Item B
|
|
|Item C ^[2]^
|
|
|
|
|Item D
|
|
|Item E ^[3]^
|
|
|Item F ^[3]^
|
|
|===
|
|
. A description.
|
|
. Another description.
|
|
. Two items relate to this description.
|
|
....
|
|
|
|
The notes immediately follow the table, instead of appearing at the bottom of the rendered assembly. With this manual method, you can also reuse the same footnote number for more than one reference.
|
|
|
|
[NOTE]
|
|
====
|
|
* Because this method uses a standard ordered list, you might find it helpful to use numbers (such as `1.` instead of `.`) while writing.
|
|
* Add a space before the superscripted numbers with square brackets.
|
|
* Older versions of these guidelines recommended the use of the deprecated `[.small]` style. The Red Hat Customer Portal does not support this style.
|
|
====
|
|
|
|
[id="collapsible-content"]
|
|
=== Collapsible content
|
|
|
|
Creating collapsible sections of content by using the `collapsible` option is not supported by our publication tooling.
|
|
|
|
=== Quick reference
|
|
|
|
.User accounts and info
|
|
[option="header"]
|
|
|===
|
|
|Markup in command syntax |Description |Substitute value in Example block
|
|
|
|
|`<username>`
|
|
|Name of user account
|
|
|user@example.com
|
|
|
|
|`<password>`
|
|
|User password
|
|
|password
|
|
|===
|
|
|
|
[IMPORTANT]
|
|
====
|
|
Do not use a password format that matches the format of a real password. Documenting such a password format can cause the following issues:
|
|
|
|
* Indicates that Red Hat publicly exposes sensitive data in their documentation.
|
|
* Leads to additional security incidents that the Information Security, InfoSec, team must investigate. Such security incidents, although minor, can impact the InfoSec team's resources and potentially delay them from focusing on actual security incidents.
|
|
====
|
|
|
|
.Projects and applications
|
|
[option="header"]
|
|
|===
|
|
|Markup in command syntax |Description |Substitute value in Example block
|
|
|
|
|`<project>`
|
|
|Name of project
|
|
|myproject
|
|
|
|
|`<app>`
|
|
|Name of an application
|
|
|myapp
|
|
|===
|
|
|
|
[id="additional-resources-sections"]
|
|
=== Additional resources sections
|
|
|
|
The following guidelines apply to all "Additional resources" sections:
|
|
|
|
* You must include the `[role="_additional-resources"]` attribute declaration before the section heading.
|
|
* You must not include paragraphs in the section. Use an unordered list.
|
|
* The links and xrefs in the unordered list must contain minimal-length, human-readable text between the square brackets. This text is often the title of the linked page.
|
|
* You must not include text outside of the square brackets. Text outside the brackets does not effectively render in an additional resources section box for a document on the Customer Portal.
|
|
|
|
Additionally, in an assembly, use `==` formatting for the section heading (`== Additional resources`). Use of this heading syntax at the assembly level indicates that the sections relate to the whole assembly. For example:
|
|
|
|
----
|
|
[role="_additional-resources"]
|
|
[id="additional-resources_{context}"]
|
|
== Additional resources
|
|
* link:example.com[IANA example domain for documentation]
|
|
* xref:../installation/installing-the-product.adoc#installing-the-product[Installing the product]
|
|
* xref:../configuration/product-settings.adoc#installation-parameters_product-settings[Product installation configuration parameters]
|
|
----
|
|
|
|
Only use `.` formatting (`.Additional resources`) in a module or to follow a module in an assembly. Because you cannot use the xrefs in modules, this functions as a _trailing include_ at the assembly level, where the `.` formatting of the `include` statement indicates that the resource applies specifically to the module and not to the assembly. For example:
|
|
|
|
----
|
|
[role="_additional-resources"]
|
|
.Additional resources
|
|
* link:example.com[IANA example domain for documentation]
|
|
* xref:../installation/installing-the-product.adoc#installing-the-product[Installing the product]
|
|
* xref:../configuration/product-settings.adoc#installation-parameters_product-settings[Product installation configuration parameters]
|
|
----
|
|
|
|
You can add link, hyperlinks, and cross references in either the _Additional resources_ section or the _Next steps_ section, but know the following differences:
|
|
|
|
Additional resources - module level:: Requires the `.Additional resources` section heading. The listed resources link to other material closely related to the contents of the module. Focus on including the most relevant resources for the user, not a full list of possibly related resources.
|
|
|
|
Additional resources - assembly level:: Requires the `== Additional resources` section heading with a unique anchor ID. If a resource applies to all of the modules in a user story, consider listing the resource in the _Additional resources_ section of the assembly file.
|
|
|
|
Next steps:: Provide links to resources that contain instructions that might be useful to the user after they complete a module or assembly. Do not use the _Next steps_ section to provide detailed instructions to documentation users.
|
|
|
|
For more information about section types, see link:https://redhat-documentation.github.io/modular-docs/#assembly-guidelines["Assembly guidelines"] in the _Modular documentation reference guide_.
|
|
|
|
== Admonitions
|
|
Admonitions such as notes and warnings are formatted as shown:
|
|
|
|
....
|
|
[ADMONITION]
|
|
====
|
|
Text for admonition
|
|
====
|
|
....
|
|
|
|
See the link:https://redhat-documentation.github.io/supplementary-style-guide/#admonitions[Red Hat Supplementary style guide] for the valid admonition types and their definitions.
|
|
|
|
[id="api-object-formatting"]
|
|
== API object formatting
|
|
|
|
For terms that are API objects, the way they are written depends on whether the term is a general reference or an actual reference to the object.
|
|
|
|
[id="api-object-general-references"]
|
|
=== General references
|
|
|
|
A general reference is any time you are speaking conceptually, or generally, about these components in a cluster.
|
|
|
|
When referring to API object terms in general usage, use lowercase and separate multi-word API objects. *Default to following this guidance unless you are specifically interacting with/referring to the API object (see xref:api-object-object-references[Object references]).*
|
|
|
|
For example:
|
|
|
|
* pod
|
|
* node
|
|
* daemon set
|
|
* config map
|
|
* deployment
|
|
* image stream
|
|
* persistent volume claim
|
|
|
|
.Examples of general references
|
|
....
|
|
Kubernetes runs your workload by placing containers into pods to run on nodes.
|
|
|
|
You must have at least one secret, config map, or service account.
|
|
|
|
The total number of persistent volume claims in a project.
|
|
....
|
|
|
|
Note that if an object uses an acronym or other special capitalization, then its general reference should honor that. For example, general references to `APIService` should be written as "API service", not "api service". Any other exceptions or special guidance are noted in the xref:../contributing_to_docs/term_glossary.adoc[glossary].
|
|
|
|
[id="api-object-object-references"]
|
|
=== Object references
|
|
|
|
An object reference is when you are referring to the actual instance of an API object, where the object name is important.
|
|
|
|
When referring to actual instances of API objects, use link:https://en.wikipedia.org/wiki/Camel_case#Variations_and_synonyms[PascalCase] and mark it up as monospace in backticks (````).
|
|
|
|
[NOTE]
|
|
====
|
|
Do not use backticks or other markup in assembly or module headings. You can use backticks or other markup in the title for a block, such as a code block `.Example` or a table `.Description` title.
|
|
====
|
|
|
|
Be sure to match the proper object type (or `kind` in Kubernetes terms); for example, do not add an "s" to make it plural. *Only follow this guidance if you are explicitly referring to the API object (for example, when editing an object in the CLI or viewing an object in the web console).*
|
|
|
|
For example:
|
|
|
|
* `Pod`
|
|
* `Node`
|
|
* `DaemonSet`
|
|
* `ConfigMap`
|
|
* `Deployment`
|
|
* `ImageStream`
|
|
* `PersistentVolumeClaim`
|
|
|
|
.Examples of API object references
|
|
....
|
|
After you create a `Node` object, or the kubelet on a node self-registers, the control plane checks whether the new `Node` object is valid.
|
|
|
|
The default amount of CPU that a container can use if not specified in the `Pod` spec.
|
|
|
|
Create a file, `pvc.yaml`, with the `PersistentVolumeClaim` object definition.
|
|
....
|
|
|
|
[NOTE]
|
|
====
|
|
Use "object", "resource", "custom resource", "spec", etc. as appropriate after the object reference. This helps with clarity and readability.
|
|
|
|
Another situation where this is necessary is when referring to the plural version of objects. Do not add an "s" to the end of an object name reference to make it plural. Use only the official `kind` of object (for example, seen when you run `oc api-resources`).
|
|
|
|
For example, the object `kind` for a node is `Node`, not `Nodes`. So do not write "You can create `Nodes` using `kubectl`." Instead, rewrite to something like "You can create `Node` objects using `kubectl`."
|
|
====
|
|
|
|
[id="operator-name-capitalization"]
|
|
=== Operator capitalization
|
|
|
|
The term "Operator" is always capitalized. For example:
|
|
|
|
----
|
|
= Support policy for unmanaged Operators
|
|
|
|
Individual Operators have a `managementState` parameter in their configuration.
|
|
----
|
|
|
|
An Operator's full name must be a proper noun, with each word initially
|
|
capitalized. If it includes a product name, defer the product's capitalization
|
|
style guidelines. For example:
|
|
|
|
- Red Hat OpenShift Logging Operator
|
|
- Prometheus Operator
|
|
- etcd Operator
|
|
- Node Tuning Operator
|
|
- Cluster Version Operator
|
|
|
|
[NOTE]
|
|
====
|
|
Red Hat Brand and Legal guidance for Operator names will likely differ. For marketing materials, they prefer lowercase names for anything that is not a Red Hat product.
|
|
|
|
However, the Brand team recognizes that there are different standards for marketing materials versus technical content. For this reason, the title case capitalization for Operator names in technical product documentation and OperatorHub is acceptable.
|
|
|
|
The "Naming" page by Red Hat Brand on the Source provides an overview of naming slide deck that also confirms this difference.
|
|
====
|
|
|
|
== Declarative config examples
|
|
|
|
Many of our procedures provide imperative `oc` commands (which cannot be stored in a Git repo). Due to efforts around improving the experience for GitOps users, we sometimes also want to provide a declarative YAML example that achieves the same configuration. This allows users to store these YAML configurations in a Git repo and follow GitOps practices to configure OpenShift.
|
|
|
|
[IMPORTANT]
|
|
====
|
|
When adding declarative examples to procedures, do not completely replace the imperative command with the declarative YAML example. Some users might still prefer the imperative option.
|
|
====
|
|
|
|
To add a declarative YAML example to a procedure step with an existing imperative command, add it in a "TIP" admonition by following the template in the example below. This example uses an imperative command (`oc create configmap`) to create a config map, and then provides the declarative YAML example of the `ConfigMap` object afterward.
|
|
|
|
....
|
|
* Define a `ConfigMap` object containing the certificate authority by using the following command:
|
|
+
|
|
[source,terminal]
|
|
----
|
|
$ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
|
|
----
|
|
+
|
|
[TIP]
|
|
====
|
|
You can alternatively apply the following YAML to create the config map:
|
|
|
|
[source,yaml]
|
|
----
|
|
apiVersion: v1
|
|
kind: ConfigMap
|
|
metadata:
|
|
name: ca-config-map
|
|
namespace: openshift-config
|
|
type: Opaque
|
|
data:
|
|
ca.crt: <base64_encoded_CA_certificate_PEM>
|
|
----
|
|
====
|
|
....
|
|
|
|
This renders as:
|
|
|
|
> * Define a `ConfigMap` object containing the certificate authority by using the following command:
|
|
> +
|
|
> [source,terminal]
|
|
> ----
|
|
> $ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
|
|
> ----
|
|
> +
|
|
> [TIP]
|
|
> ====
|
|
> You can alternatively apply the following YAML to create the config map:
|
|
>
|
|
> [source,yaml]
|
|
> ----
|
|
> apiVersion: v1
|
|
> kind: ConfigMap
|
|
> metadata:
|
|
> name: ca-config-map
|
|
> namespace: openshift-config
|
|
> type: Opaque
|
|
> data:
|
|
> ca.crt: <base64_encoded_CA_certificate_PEM>
|
|
> ----
|
|
> ====
|
|
|
|
[NOTE]
|
|
====
|
|
If you are adding a particularly long YAML block, you can optionally use the xref:collapsible-content[`%collapsible`] feature to allow users to collapse the code block.
|
|
====
|
|
|
|
== Quick markup reference
|
|
|
|
|===
|
|
|Convention |Markup |Example rendered output
|
|
|
|
|Code blocks
|
|
|
|
a|
|
|
....
|
|
Use the following syntax for the `oc` command:
|
|
|
|
----
|
|
$ oc <action> <object_type> <object_name_or_id>
|
|
----
|
|
....
|
|
|
|
a|
|
|
> Use the following syntax for the `oc` command:
|
|
>
|
|
> ----
|
|
> $ oc <action> <object_type> <object_name_or_id>
|
|
> ----
|
|
|
|
a|Use backticks for all non-GUI "system items", including:
|
|
|
|
* Inline commands, operations, literal values, variables, parameters, settings,
|
|
flags, environment variables, user input
|
|
* System term/item, user names, unique or example names for individual API
|
|
objects/resources (e.g., a pod named `mypod`), daemon, service, or software
|
|
package
|
|
* RPM packages
|
|
* File names or directory paths
|
|
|
|
a|
|
|
....
|
|
`oc get`
|
|
|
|
Set the `upgrade` variable to `true`.
|
|
|
|
Use the `--amend` flag.
|
|
|
|
Answer by typing `Yes` or `No` when prompted.
|
|
|
|
`user_name`
|
|
|
|
`service_name`
|
|
|
|
`package_name`
|
|
|
|
`filename`
|
|
....
|
|
|
|
a|
|
|
> Use the `oc get services` command to get a list of services that are currently defined.
|
|
>
|
|
>
|
|
>
|
|
> Use the `--amend` flag.
|
|
>
|
|
>
|
|
>
|
|
> Set the `upgrade` variable to `true`.
|
|
>
|
|
>
|
|
>
|
|
> Answer by typing `Yes` or `No` when prompted.
|
|
>
|
|
>
|
|
>
|
|
> `cluster-admin` user
|
|
>
|
|
>
|
|
>
|
|
> `firewalld` service
|
|
>
|
|
>
|
|
>
|
|
> `rubygems` RPM package
|
|
>
|
|
>
|
|
>
|
|
> The `express.conf` configuration file is located in the `/usr/share` directory.
|
|
|
|
|System or software variable to be replaced by the user
|
|
a|
|
|
....
|
|
`<project>`
|
|
|
|
`<deployment>`
|
|
|
|
`<install_mode_value>`
|
|
....
|
|
|
|
a|
|
|
> Use the following command to roll back a Deployment, specifying the Deployment name:
|
|
>
|
|
> `oc rollback <deployment>`
|
|
>
|
|
>
|
|
>
|
|
> Apply the new configuration file:
|
|
>
|
|
> `oc apply -f <path_to_configuration_file>/<filename>.yaml`
|
|
|
|
|Use single asterisks for web console/GUI items (menus, buttons, page titles, etc.).
|
|
Use two characters to form the arrow in a series of menu items (`$$->$$`).
|
|
|
|
a|
|
|
....
|
|
Choose *Cluster Console* from the list.
|
|
|
|
Navigate to the *Operators* -> *Catalog Sources* page.
|
|
|
|
Click *Create Subscription*.
|
|
....
|
|
|
|
a|
|
|
> Choose *Cluster Console* from the list.
|
|
>
|
|
>
|
|
>
|
|
> Navigate to the *Operators* -> *Catalog Sources* page.
|
|
>
|
|
>
|
|
>
|
|
> Click *Create Subscription*.
|
|
|
|
|Use underscores to emphasize the first appearance of a new term.
|
|
|
|
a|
|
|
....
|
|
An _Operator_ is a method of packaging, deploying,
|
|
and managing a Kubernetes application.
|
|
....
|
|
|
|
a|
|
|
> An _Operator_ is a method of packaging, deploying, and managing a Kubernetes application.
|
|
|
|
|Use of underscores for general emphasis is allowed but should only be used
|
|
very sparingly. Let the writing, instead of font usage, create the emphasis
|
|
wherever possible.
|
|
|
|
a|
|
|
....
|
|
Do _not_ delete the file.
|
|
....
|
|
|
|
a|
|
|
> Do _not_ delete the file.
|
|
|
|
|Table style operators
|
|
|
|
|A style operator styles the content of a table cell or a table column, depending on where you set the operator. Using the literal (`l`) operator in a column might impact the documentation platform's copy and paste functionality. For example, when you paste copied code block content to a location, the first styled literal value in an assembly is pasted instead of the intended code block. When using any style operator in a table, check all copy and paste functions that follow the defined style operator work correctly for all code blocks in an assembly.
|
|
|
|
See link:https://docs.asciidoctor.org/asciidoc/latest/tables/format-cell-content/[Cell styles and their operators] (Asciidoctor Documentation)
|
|
|
|
a|
|
|
----
|
|
.Required parameters
|
|
[cols=".^2m,.^3,.^5a",options="header"]
|
|
----
|
|
|
|
|Footnotes
|
|
|
|
|A footnote is created with the footnote macro. If you plan to reference a footnote more than once, use the ID footnoteref macro. The Customer Portal does not support spaces in the footnoteref. For example, "dynamic PV" should be "dynamicPV".
|
|
|
|
|For footnote and footnoteref syntax, see link:http://asciidoctor.org/docs/user-manual/#user-footnotes[AsciiDoctor documentation].
|
|
|
|
|===
|