Asciidoc getting started

Getting Started with Asciidoc : Syntax

Joseph Cayouette v1.0, 2018-05-03

🔥	This page is out of date!

Introduction

This document provides commonly used asciidoc syntax examples.

How to Contribute

SUSE Manager documentation can be found here:

• https://github.com/SUSE/doc-susemanager

❗	We treat documentation as code (branch, fix, pull request, review merge)

Asciidoctorjs Browser Extension

You can preview an AsciiDoc document in a web browser by installing the Chrome extension, the Firefox add-on or the Opera extension. After installation you can visit a raw adoc document on github and it will render in html fully styled.

If you are working locally make sure to go to the extension settings and enable the Allow access to file URLs toggle.

ℹ️

Content listed in this document was drafted from the following sources. If you are interested in heavy contribution then the more advanced official documentation will help you get started, see: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ https://asciidoctor.org/docs/asciidoc-writers-guide/ https://asciidoctor.org/docs/user-manual/ https://asciidoctor.org/docs/asciidoc-recommended-practices/

Asciidoc Best Practice

One sentence per line

Don’t wrap text at a fixed column width. Instead, put each sentence on its own line, a technique called sentence per line. Use soft wrap in your editor if you need a temporary wrap solution.

For more information see:

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

This is a sentence.
This is also a sentence.
This is another sentence.

This is a sentence. This is also a sentence. This is another sentence.

Asciidoc Syntax

Section Headings

Add 3 line breaks between sections. Add one line break between all other content blocks. This helps visually when editing the source document.

Article doctype

= Document Title (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

====== Level 5 Section Title

== Another Level 1 Section Title

Example line breaks 3 per section, 1 per content.:

[[_s2_sattools_org_details_details]]
=== menu:Organizations[Organization Details]

The menu:Organization[Organization Details] page lists the details of the selected organization.

image::admin_organization_details.png[scaledwidth=80%]

The following details are available:

* menu:Organization Details[Organization Name] : String (between 3 and 128 characters).
This is the only value that you can change here.
When done, confirm with clicking the btn:[Update Organization] button.
* menu:Organization Details[Organization ID] : Number
* menu:Organization Details[Active Users] : Number. Clicking this number will open the menu:Organization Details[Users] tab. For more information, see <<_s2_sattools_org_details_users>>.
* menu:Organization Details[Systems] : Number
* menu:Organization Details[System Groups] : Number
* menu:Organization Details[Activation Keys] : Number
* menu:Organization Details[Autoinstallation Profiles] : Number
* menu:Organization Details[Configuration Channels] : Number



[[_s2_sattools_org_details_users]]
=== menu:Organization Details[Users]

List of all the users of an organization.

image::admin_organization_users.png[scaledwidth=80%]

You can modify the user details if you belong to that organization and have organization administrator privileges.
For more information, see <<_ref.webui.admin.users>>.



[[_s2_sattools_org_details_trust]]
=== menu:Organization Details[Trust]

Here establish trust between organizations.

image::admin_organization_trusts.png[scaledwidth=80%]

Such a trust allows sharing contents and migrate systems between these two organizations.
You may add a trust by checking the box next to an organization (or remove a trust by unchecking it) and clicking the menu:Modify Trusts[] button.

Paragraphs

Paragraphs don’t require any special markup in AsciiDoc.

A paragraph is just one or more lines of consecutive text.
Keep in mind of course one sentence per line!

---

Formatted Text

Bold, Italic and Monospace text.

*bold phrase* & **char**acter**s**

_italic phrase_ & __char__acter__s__

*_bold italic phrase_* & **__char__**acter**__s__**

`monospace phrase` & ``char``acter``s``

`*monospace bold phrase*` & ``**char**``acter``**s**``

`_monospace italic phrase_` & ``__char__``acter``__s__``

`*_monospace bold italic phrase_*` &
``**__char__**``acter``**__s__**``

---

Rendered Formatted Text:

bold phrase & characters

italic phrase & characters

bold italic phrase & characters

monospace phrase & characters

monospace bold phrase & characters

monospace italic phrase & characters

monospace bold italic phrase & characters

Lists

List should have an empty line both above and below them.

Unordered, basic

* Edgar Allen Poe
* Sheri S. Tepper
* Bill Bryson

• Edgar Allen Poe

• Sheri S. Tepper

• Bill Bryson

---

Unordered, nesting

* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1

• level 1

  • level 2

    • level 3

      • level 4

        • level 5

• level 1

---

Ordered, basic

. Step 1
. Step 2
. Step 3

1. Step 1

2. Step 2

3. Step 3

---

Ordered, max nesting

. level 1
.. level 2
... level 3
.... level 4
..... level 5
. level 1

1. level 1

   1. level 2

      1. level 3

         1. level 4

            1. level 5

2. level 1

Labeled Definitions

You may use either single or multi-line definitions. Labeled definitions are called formal paragraphs in docbook.

Labeled, single-line

first term:: definition of first term
second term:: definition of second term

first term

definition of first term

second term

definition of second term

---

Labeled, multi-line

first term::
definition of first term
section term::
definition of second term

first term

definition of first term

section term

definition of second term

Images

Using Images

1. Place new images within the doc-susemanager/adoc/images` directory.

2. Add the :imagesdir: images: attribute to the document header.

image::books2.jpg[]

image::books2.jpg[Books]

.A mountain sunset
[#img-books2]
[caption="Figure 1: ",link=https://www.suse.com/brandcentral/suse/]
image::books2.jpg[Book 2,300,200]

image::https://asciidoctor.org/images/octocat.jpg[GitHub mascot]

Figure 1: A Bunch of Moldy Books

Links

External

https://asciidoctor.org - automatic!

https://asciidoctor.org[Asciidoctor]

https://github.com/asciidoctor[Asciidoctor @ *GitHub*]

https://asciidoctor.org - automatic!

Asciidoctor

Asciidoctor @ GitHub

---

Internal Cross References

Add an id above any section in your document (In this case labeled definitions):

[#labeled]

Then make the reference:

See xref:#labeled[Labeled] to learn how to use labels.

See Labeled to learn how to use labels.

---

Inter-document Cross References

To make a cross document reference use xref: followed by the filename, then the id and then the link text in square brackets.

Refer to xref:filename.adoc#section-id[Link Text] for more information.

See you when you get back from Link Text.

Admonitions (Note, Tip, Warning, Important, Caution)

You can use admonitions in your documents. Add the following conditional ifdef statement to your document header to render admonitions on github. Look at this document in RAW if you need an example.

ifdef::env-github[]
//Admonitions
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

Create an admonition:

[NOTE]
.Note Admonition
====
An admonition paragraph draws the reader's attention to
auxiliary information.
Its purpose is determined by the label
at the beginning of the paragraph.
====

Here are the other built-in admonition types:

[TIP]
.Tip Admonition
====
Pro tip...
====

[IMPORTANT]
.Important Admonition
====
Don't forget...
====

[WARNING]
.Warning Admonition
====
Watch out for...
====

[CAUTION]
.Caution Admonition
====
Ensure that...
====

Rendered Admonitions:

ℹ️	Note Admonition An admonition paragraph draws the reader’s attention to auxiliary information. Its purpose is determined by the label at the beginning of the paragraph.

Here are the other built-in admonition types:

💡	Tip Admonition Pro tip…​

❗	Important Admonition Don’t forget…​

⚠️	Warning Admonition Watch out for…​

🔥	Caution Admonition Ensure that…​

---

Using IDs Properly

You can use objects as the uppermost item for any adoc element. These can be used as cross references or as links. Use ids for objects in your documents similar to the following:

[[gs-introduction]]
[[ref-systems-all-systems]]
[[bp-icinga-guide]]
[[at-command-line-tools]]

For example if you would like to give a section an id:

[[gs-getting-started-with-salt]]
== Getting Started with Salt

This section covers...

Admonition Example

[[ref-caution-ensure-that]]
[CAUTION]
.Caution Admonition
====
Ensure that...
====

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::[]