Every topic file should contain the following metadata at the top, with no line spacing in between, except where noted:
= Document/Topic Title (1)
{product-author} (2)
{product-version} (3)
:data-uri: (4)
:icons: (5)
:toc: macro (6)
:toc-title: (7)
:description: <Brief description of content for search> (8)
-----------intentional blank line--------------
toc::[] (9)
-
Human readable title of document/topic title line (notice the '=' top-level header)
-
AsciiDoctor attribute for product author and gets dynamically replaced
-
AsciiDoctor attribute for product version and gets dynamically replaced
-
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.
-
Brief description or synopsis of the document/topic to help with Google search.
-
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. |
If using section anchors, they must be all lowercase letters, with no line spaces between the anchor and the section title:
[[section-anchor-name]] === Section Title
There are some general guidelines and conventions we follow for titles, headings, and topic filenames. These are described in the following table.
| Example | Description | |
|---|---|---|
Topic filenames |
manage_authorization_policies.adoc |
Try to shorten the topic filename as much as possible WITHOUT abbreviating important terms that may cause confusion. In this example, this topic filename would be appropriate for a topic titled Managing Authorization Policies. |
Topic / section titles |
Managing Authorization Policies |
Try to be as descriptive as possible with the topic title or section headings without making them unnecessarily too long. Most importantly, we use title case in all topic titles and section headings. See http://titlecase.com/ for more information. |
Links can be used to cross-reference internal topics, or send customers to external information resources for further reading.
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".
Rollbacks revert part of an application back to a previous deployment. Rollbacks can be performed using the REST API or the link:cli.html#deployment-rollbacks[OpenShift CLI]. Before you can create a domain, you must first link:applications.html#create_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.
For comparison and clarification, the following example shows the previous method of linking to other topics. Do not use the old method of linking to internal topics, as shown in the following examples.
Rollbacks revert an application back to a previous deployment and can be performed using the REST API or the OpenShift CLI. See the link:cli.html#deployment-rollbacks[CLI documentation] for more information. Before you can create a domain, you must first create an application. See link:applications.html#create_app[Create an Application] for information on how to create an application.
This example renders like so:
Rollbacks revert an application back to a previous deployment and can be performed using the REST API or the OpenShift CLI. See the CLI documentation for more information.
Before you can create a domain, you must first create an application. See Create an Application for information on how to create an application.
The difference here is that in the first example the link to [create an application] is part of the actual sentence. In the second example, both links are sentences that begin with "See….", which is not recommended.
If you want to link to a different website, use:
http://othersite.com/otherpath[friendly descriptor]
|
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 two 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
link:<filename>[friendly title]
Do not 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:
link:zag.html[comment]
Link to topic in different topic group directory
link:../dir/<filename>.html[friendly title]
For example, if you are working on bar.adoc and you want to link to zig.adoc, do it this way:
link:../baz/zig.html[see the ZIG manual for more]
|
Note
|
You must use the .html extension in order for the link to work correctly. |
Link to a subtopic within a topic file
To link to a subtopic within a topic file, use the following syntax:
link:../baz/zig/#subtopic
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 dita 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 show replaceables within code blocks.
-
Do NOT use any markup in code blocks; code blocks generally do not accept any markup
-
Try to use callouts to provide information on what the output represents when required
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.
Do NOT show full commands or command syntax inline within a sentence. See Command syntax and examples for information on 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 actual output of that command, where applicable.
To markup command syntax, use the sidebar block with the <replaceable> markup and 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: **** `osc get _<object_type>_ _<object_id>_` ****
This would render as follows:
The following command returns a list of objects for the specified object type:
osc 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 `osc get` operation returns a complete list of services that are currently defined. .Example Title ==== ---- $ osc 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 osc get operation returns a complete list of services that are currently defined.
$ osc 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
Lists 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 |
|---|---|---|
Inline commands, operations, and user input |
`osc get` `GET` Answer by typing `Yes` or `No` when prompted. |
Use the The Answer by typing |
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:
This is ONLY used when showing the command syntax using the sidebar block. |
System or software configuration parameter or environment variable |
`*ENVIRONMENT_VARIABLE*` `*PARAMETER*` |
Use the The |
System term, daemon, service, or software package |
*system item* *daemon* *service* *software package* |
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. |