markup syntax
Lana Brindley v2.0, 2018-08-23
Joseph Cayouette v1.0, 2018-05-03
This document contains a guide to our markup and syntax conventions.
| Content type | Markup | Example |
|---|---|---|
Paths and filenames |
[path]``foo`` |
|
Commands |
[command]``foo`` |
|
Packages |
[package]``foo`` |
|
Anything not covered under the above |
[systemitem]``foo`` |
|
GUI nested menus |
menu:foo[bar] and menu:foo[bar > bat] |
File › Save and View › Toolbars › Editing |
GUI buttons |
btn:[foo] |
Save |
Components in a GUI that are not nested menus or buttons |
[guimenu]``foo`` |
|
Keyboard key |
kbd:[foo] |
Enter |
Keyboard key combo |
kbd:[foo + bar] |
Ctrl+S |
This section contains general guidance on how we structure the code in our documentation.
Put each sentence on its own line, and leave a line break between paragraphs Do not wrap text at a fixed column width.
If you need to, you can use a soft wrap in your editor to wrap longer lines.
This is a sentence. This is also a sentence. This is a new paragraph. This is the second sentence in the second paragraph.
Use three blank lines before a heading or sub-heading, including procedures.
Add one blank line between all other content blocks, including admonitions.
Each sentence should start on a new line.
This is an example of a stem sentence: \---- This is a line of code \---- == This is a new heading This is a sentence. This is another sentence.
Do not use bold, italic, or monospace formatting in SUSE Manager documentation. Instead, use proper markup.
List should have an empty line both above and below them. Remember to use ordered lists only when the order of the items is important.
* List item 1 * List item 2 ** Sub-item * List item 3 ** Sub-item *** Sub-sub-item
-
List item 1
-
List item 2
-
Sub-item
-
-
List item 3
-
Sub-item
-
Sub-sub-item
-
-
. Step 1 . Step 2 .. Sub-step . Step 3 .. Sub-step ... Sub-sub-step
-
Step 1
-
Step 2
-
Sub-step
-
-
Step 3
-
Sub-step
-
Sub-sub-step
-
-
Word 1:: Definition of word 1 Word 2:: . First definition of word 2 . Second definition of word 2
- Word 1
-
Definition of word 1
- Word 2
-
-
First definition of word 2
-
Second definition of word 2
-
This shows the syntax for writing procedures. Also check the Word Usage Guide for more on how to write processes and procedures.
.Procedure: Naming the Procedure . Step one . Step two .. Sub-step . Step three .. Sub-step ... Sub-sub-step
-
Step one
-
Step two
-
Sub-step
-
-
Step three
-
Sub-step
-
Sub-sub-step
-
-
To include block elements in prose, leave a blank line before and after the block:
This is surrounding text \ ---- rm -rf * \ ----
This is surrounding text
rm -rf *
To add a block element to a procedure, use the + sign to continue the numbering properly:
. This is the first step . This is the second step, with a code block: + \ ---- rm -rf * \ ---- . This is the third step
-
This is the first step
-
This is the second step, with a code block:
rm -rf *
-
This is the third step
Put the image file (as a .png) into the /assets/images directory of the book you want to add it to.
At the appropriate location in the text, include this line:
image::image_filename.png[scaledwidth=80%]
https://asciidoctor.org
For more information, see xref:example.adoc[].
For more information, see example.asciidoc.
We use three admonition types: Note, Important, and Warning.
[NOTE] ==== Extra information that might be useful. ====
|
ℹ️
|
Extra information that might be useful. |
[IMPORTANT] ==== Important information that the reader will need to be aware of. ====
|
❗
|
Important information that the reader will need to be aware of. |
[WARNING] ==== Ignoring this information could lead to data loss. ====
|
|
Ignoring this information could lead to data loss. |
You can specify content that should not be rendered in production documentation, for example for feature docs in development.
To use draft syntax, add the :drafts: attribute to the header of the page.
For example:
:draft:
ifndef::draft[]
This will not be rendered in production docs.
endif::[][cols="1,1", options="header"]
.Table title
|===
| Column A | Column B
| Cell content | Cell content.
Longer Column B cell content.
| Cell content.
Longer Column A content | Cell content
| Cell content | Cell content
|===
| Column A | Column B |
|---|---|
Cell content |
Cell content. Longer Column B cell content. |
Cell content. Longer Column A content |
Cell content |
Cell content |
Cell content |
We generate both SUMA and Uyuni documentation from the same source.
Avoid specifying either SUMA or Uyuni in the documentation.
Always use the {productname} entity instead, so that it is properly replaced at build time.
If the content you are writing only applies to one product and not both, use the {productname} entity as usual, but wrap the content in an ifeval statement.
Always check that your ifevals are working correctly when you create a PR by building the docs locally.
// This is content that applies to both products.
To install the {productname} Server:
/ifeval::[{uyuni-content} == true]
// This content only applies to Uyuni.
Download the ISO for the {productname} Server.
/endif::[]
/ifeval::[{suma-content} == true]
// This content only applies to SUMA.
Ensure you have the correct credentials for the {productname} Server.
/endif::[]
// This is content that applies to both products.
When you have completed installation, you can set up the {productname} Server.
For Uyuni, this renders at build time as:
To install the Uyuni Server: Download the ISO for the Uyuni Server. When you have completed installation, you can set up the Uyuni Server.
For SUMA, this renders at build time as:
To install the SUSE Manager Server: Ensure you have the correct credentials for the SUSE Manager Server. When you have completed installation, you can set up the SUSE Manager Server.
To create a cross-reference, use this syntax:
For more information, see xref:installation:server-install.adoc[]
Ensure you always use the full path in the cross-reference, including the book name. This will prevent xrefs from breaking if the content is moved, and also renders better in PDF (where readers need to be able to parse the link themselves, without being able to click).
