markup syntax

Markup and Syntax Guide

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.

Markup Guide

Content type	Markup	Example
Paths and filenames	[path]``foo``	`/dev/null`
Commands	[command]``foo``	`ls -l`
Packages	[package]``foo``	`spacewalk`
Anything not covered under the above	[systemitem]``foo``	`SLE-15-x86_64`
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``	`System Details`
Keyboard key	kbd:[foo]	`Enter`
Keyboard key combo	kbd:[foo + bar]	`Ctrl`+`S`

Syntax Guide

This section contains general guidance on how we structure the code in our documentation.

One sentence per line

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.

https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line

This is a sentence.
This is also a sentence.

This is a new paragraph.
This is the second sentence in the second paragraph.

Whitespace

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.

Formatted Text

Do not use bold, italic, or monospace formatting in SUSE Manager documentation. Instead, use proper markup.

Lists

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.

Unordered List:

* 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

Ordered List:

. Step 1
. Step 2
.. Sub-step
. Step 3
.. Sub-step
... Sub-sub-step

Step 1
Step 2
1. Sub-step
Step 3
1. Sub-step
  1. Sub-sub-step

Definition List:

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

Procedures

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

Procedure: Naming the Procedure

Step one
Step two
1. Sub-step
Step three
1. Sub-step
  1. Sub-sub-step

Block elements

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

Images

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%]

Links

External Links:

https://asciidoctor.org

https://asciidoctor.org

Internal Cross-References:

For more information, see xref:example.adoc[].

For more information, see example.asciidoc.

Admonitions

We use three admonition types: Note, Important, and Warning.

Note:

[NOTE]
====
Extra information that might be useful.
====

ℹ️	Extra information that might be useful.

Important:

[IMPORTANT]
====
Important information that the reader will need to be aware of.
====

❗	Important information that the reader will need to be aware of.

Warning:

[WARNING]
====
Ignoring this information could lead to data loss.
====

⚠️	Ignoring this information could lead to data loss.

Working with Drafts

You can specify content that should not be rendered in production documentation. (Feature docs in development) To use draft syntax, add the :drafts: attribute to the header of For example:

:draft:

ifndef::draft[]
This will not be rendered in production docs.
endif::[]

Tables

[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
|===