Every topic file should contain the following metadata at the top, with no line spacing in between, except where noted:
= Document/Topic Title (1) :data-uri: (2) :icons: (3) :toc: macro (4) :toc-title: (5) -----------intentional blank line-------------- toc::[] (6)
-
Human readable title of document/topic title line (notice the '=' top-level header)
-
AsciiDoctor attribute to embed all images directly in the HTML
-
AsciiDoctor attribute for icons used in admonitions and such (TIP, NOTE, WARNING, etc.)
-
Adds a table of contents (TOC) with manual placement.
-
Overrides the default title of TOC and removes the title.
-
Placement of the TOC.
After the heading block and a single whitespace line, you can include any content for the topic.
|
Note
|
The topic title, which is the first line of the document, is the only level 1 ( = ) title. Section headers within the topic must be level 2 ( == ) or lower. |
All titles must have a unique (within the OpenShift docs suite) section anchor, and this anchor must be all lowercase letters, with no line spaces between the anchor and the section title:
[[section-anchor-name]] === Section Title
Try to shorten the topic 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 a
topic titled "Managing Authorization Policies".
Use sentence case in all topic 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 topic title or section headings without making them unnecessarily too long. Use a verb form in headings. Some suggestions:
-
Creating
-
Managing
-
Using
-
Understanding
Use "Overview" as a heading sparingly. Choose a more descriptive heading instead.
The content in this repo is used to build docs that publish to multiple
locations (e.g., docs.openshift.com, docs.openshift.org, and the Red Hat
Customer Portal). While heading IDs will be created automatically from any
section titles (e.g., "Managing Authorization Policies" would generate an ID of
managing-authorization-policies, which would act as an anchor reference), we
should not rely on this automatic generation because the IDs need to be unique
across all topics in the repo. This is mainly to avoid build failures for the
Customer Portal docs, due to ID collision.
Therefore, always add a unique ID manually, and check the repo to make sure that
it is unique and not already in use (for example, check with CTRL+F to search
the repo if using Atom).
Manual IDs use the following syntax:
[[managing-authorization-policies]] == Managing Authorization Policies
If you have a section heading that you do not want to appear in the TOC (like if you think that some section is not worth showing up or if there are already too many nested levels), you can use a discrete (or floating) heading:
A discrete heading also will not get a section number in the Customer Portal
build of hte doc. Previously, we would use plain bold mark-up around a heading
like this, but discrete headings also allow you to ignore section nesting rules
(like jumping from a == section level to a ==== level if you wanted for some
style reason).
To use a discrete heading, just add [discrete] to the line before your unique
ID. For example:
[discrete] [[managing-authorization-policies]] == Managing Authorization Policies
When possible, generalize references to the product name and/or version using
the {product-title} and/or {product-version} attributes. These attributes
are pulled from distro mapping definitions in the
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 slate of distros and the
possible values for {product-title} and {product-version}.
| Distro | {product-title} |
{product-version} |
|---|---|---|
|
OpenShift Origin |
Latest |
|
OpenShift Enterprise |
3.1, 3.0 |
|
OpenShift Dedicated |
3.1, 3.0 |
|
OpenShift Online |
Latest |
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
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 Enterprise."
And for the openshift-origin distro:
"You can deploy applications on OpenShift Origin."
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 need for it. Just consider
how it will render across any branches that the content appears in.
Do not use markup in headings.
Links can be used to cross-reference internal topics, or send customers to external information resources for further reading.
In OpenShift docs:
-
all links to internal topics are created using
xrefand must have an anchor ID. -
all links to external websites are created using
link.
|
Important
|
Do not split link paths across lines when wrapping text. This will cause issues with the doc builds. |
To provide an example URL path that you do not want to render as a hyperlink, use this format:
`\https://www.example.com`
Whenever possible the link to another topic should be part of the actual sentence. Avoid creating links as a separate sentence that begins with "See [this topic] for more information on x".
|
Note
|
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 would need to include the path back to the first level of the topic directory: xref:../../architecture/networking/routes.adoc#architecture-core-concepts-routes |
Rollbacks revert part of an application back to a previous deployment. Rollbacks can be performed using the REST API or the xref:../cli_reference/get_started_cli.adoc#installing-the-cli[OpenShift CLI]. Before you can create a domain, you must first xref:../dev_guide/application_lifecycle/new_app.adoc#dev-guide-new-app[create an application].
Rollbacks revert part of an application back to a previous deployment. Rollbacks can be performed using the REST API or the OpenShift CLI.
Before you can create a domain, you must first create an application.
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.
|
|
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.
|
There probably are three scenarios for linking to other content:
-
Link to another topic file that exists in the same topic group, or directory.
-
Link to another topic file that exists in a separate topic group, or directory.
The following examples use the example directory structure shown here:
/ /foo /foo/bar.adoc /baz /baz/zig.adoc /baz/zag.adoc
Link to topic in same topic group 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 topic in different topic group directory
xref:../dir/<filename>.adoc[friendly title]
For example, if you are working on bar.adoc and you want to link to zig.adoc, do it this way:
xref:../baz/zig.adoc#baz-zig[see the ZIG manual for more]
|
Note
|
You must use the .adoc extension in order for the link to work correctly and you must specify an anchor ID. |
Link to a subtopic within a topic file
To link to a subtopic within a topic file, use the following syntax:
xref:../baz/zig/#subtopic
Link to a subtopic within the same topic file
To link to a subtopic within the same topic file, use the following syntax:
xref:subtopic
Note: There is no # used when linking to a subtopic within the same topic.
If you want to share content from one topic so that it appears in another topic,
you can use the include directive. See the Asciidoctor documentation for
details:
If you find that you need to include content from one topic multiple times into another topic, see the following usage:
A concept is a topic (full .adoc file) or section (individual heading within a topic) that supports the things that users want to do and should not include task information like commands or numbered steps. Consider topic/section titles with a verb like "Understanding <concept>" if it is solely concept-based.
A task is a topic (full .adoc file) or section (individual heading within a topic) that supports the things that users want to do and includes procedural information like commands and numbered steps. Write tasks in the following format.
Task Title: Use a verb in the task title (for example, Create or Creating).
Include a paragraph explaining why the user must perform this task. This should be 1-2 sentences maximum.
If applicable, include any gotchas (things that could trip up the user or cause the task to fail).
Before You Begin
-
A bulleted list of pre-requisites that MUST be performed before the user can complete this task. Skip if there isn’t any related information.
Procedure
-
Step 1 - One command per step.
-
Step 2 - One command per step.
-
Step N
After You Finish
You can explain any other tasks that MUST be completed after this task. You can skip this if there are none.
Related Information
-
A bulleted list of links to related information about this task. Skip if there isn’t any related information.
If you want to link to an image:
-
Put it in
<topic_dir>/images -
In the topic document, use this format to link to an image:
image::<name_of_image>[image]
You only need to specify <name_of_image>. The build mechanism automatically specifies the file path.
AsciiDoctor provides a set of extensions to embed diagrams written using PlantUML, Graphviz, ditaa, or Shaape syntax inside your AsciiDoc documents. The diagram extension generates an SVG, PNG, or TXT file from the source text. The image file that’s generated then gets inserted into the rendered document.
|
Important
|
The AsciiDoctor diagram extension serves a starting point for creating images in OpenShift documentation. In most cases these images will be professionally enhanced to meet our internal standards and guidelines. |
See the AsciiDoctor diagram extension documentation for instructions on how to install and use it.
We will mostly use the ditaa block in OpenShift documentation. The png file from the ditaa block is generated in the same directory as the source file with a checksum as the filename. However, you can specify the path of the generated png file with the second attribute in the ditaa block.
For example, in our case we would want our images in the topic_dir/images folder of the main topic directory:
.... [ditaa, "images/name_of_image"] ....
For all of the system blocks including table delimiters, use four characters. For example:
|=== for tables ---- for code blocks
Code blocks are used to show examples of command screen outputs, or configuration files. When using command blocks, always use the actual values for any items that a user would normally replace. Code blocks should represent exactly what a customer would see on their screen. If you need to expand or provide information on what some of the contents of a screen output or configuration file represent, then use callouts to provide that information.
Follow these general guidelines when using code blocks:
-
Do NOT use any markup in code blocks; code blocks generally do not accept any markup.
-
For all code blocks, you must include an empty line above a code block.
Acceptable:
Lorem ipsum ---- $ lorem.sh ----
Not acceptable:
Lorem ipsum ---- $ lorem.sh ----
Without the line spaces, the content is likely to be not parsed correctly.
-
It is recommended to include source tags for the programming language used in the code block to enable syntax highlighting. For example, use the source tags
[source, bash],[source, yaml],[source, javascript].Lorem ipsum [source, bash] ---- $ lorem.sh ----
-
Try to use callouts to provide information on what the output represents when required.
Use this format when embedding callouts into the code block:
[source, bash] ---- code example 1 <1> code example 2 <2> ---- <1> A note about the first example value. <2> A note about the second example value.
-
For long lines of code that you want to break up among multiple lines, use a backslash to show the line break. For example:
$ 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 }' -
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:# sudo ./openshift start
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.
The main distinction between showing command syntax and example is that a command syntax should just show customers how to use the command without real values. An example on the other hand should show the command with actual values with an example output of that command, where applicable.
To markup command syntax, use the code block and wrap the replaceables in <> with the required command parameters, as shown in the following example. Do NOT use commands or command syntax inline with sentences.
The following command returns a list of objects for the specified object type: [source, bash] ---- $ oc get <object_type> <object_id> ----
This would render as follows:
The following command returns a list of objects for the specified object type:
$ oc get <object_type> <object_id>As mentioned an example of a command should use actual values and also show an output of the command, as shown in the following example. In some a heading may not be required.
In the following example the `oc get` operation returns a complete list of services that are currently defined. .Example Title [source, bash] ---- $ oc get se 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 would render as shown:
In the following example the oc get operation returns a complete list of services that are currently defined.
$ oc get se
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 5001Lists are created as shown in this example:
. Item 1 (2 spaces between the period and the first character) . Item 2 . Item 3
This will render as such:
-
Item 1
-
Item 2
-
Item 3
If you need to add any text, admonitions, or code blocks you need to add the continuous +, as shown in the example:
. Item 1 + ---- some code block ---- . Item 2 . Item 3
This renders as shown:
-
Item 1
some code block
-
Item 2
-
Item 3
| Markup in command syntax | Description | Substitute value in Example block |
|---|---|---|
<username> |
Name of user account |
|
<password> |
User password |
password |
| Markup in command syntax | Description | Substitute value in Example block |
|---|---|---|
<project> |
Name of project |
myproject |
<app> |
Name of an application |
myapp |
Admonitions such as notes and warnings are formatted as shown:
[ADMONITION] ==== Text for admonition ====
| Convention | Markup | Example rendered output |
|---|---|---|
Code blocks |
Use the following syntax for the `oc` command: ---- $ oc <action> <object_type> <object_name_or_id> ---- |
Use the following syntax for the $ oc <action> <object_type> <object_name_or_id> |
Inline commands, operations, literal values, variables, parameters, settings, flags, environment variables, and user input. In general (when inline within sentences), something that either operates or acts on something else, or when referencing some item from a file or code block / example. |
`oc get` `GET` Set the `upgrade` variable to `true`. Answer by typing `Yes` or `No` when prompted. Use the `--amend` flag. |
Use the The Set the Answer by typing Use the |
System or software variable to be replaced by the user |
`<project>` `<deployment>` |
Use the following command to roll back a deployment, specifying the deployment name:
|
System term/item, user names, unique or example names for individual API objects/resources (e.g., a pod named "mypod"), GUI menu items and buttons, daemon, service, or software package. In general (when inline within sentences), something that can be operated or acted upon, or unique or example names for system terms/items in general. |
*system item* *daemon* *service* *software package* |
cluster-admin user atomic-openshift-master-api service HTTPD NetworkManager RubyGems |
Filenames or directory paths |
*_filename_* *_directory_* |
Edit the kubeconfig file as required and save your changes. The express.conf configuration file is located in the /usr/share directory. |
Emphasis for a term |
only emphasize _first_ time |
only emphasize first time |
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". |
See Footnotes for the footnote and footnoteref syntax. |