= Getting Started with Asciidoc : Syntax

Joseph Cayouette
v1.0, 2018-05-03

ifdef::env-github[]
// Admonitions
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
// Table of contents
:toc:
// Section options
:sectlinks:
:sectanchor:
:imagesdir: images
endif::[]
:imagesdir: images
:sourcedir: .
:uri-chrome-extension: https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia
:uri-firefox-addon: https://addons.mozilla.org/en/firefox/addon/asciidoctorjs-live-preview
:uri-opera-extension: https://addons.opera.com/fr/extensions/details/asciidoctorjs-live-preview
:experimental:

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

[IMPORTANT]
====
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 {uri-chrome-extension}[Chrome extension], the {uri-firefox-addon}[Firefox add-on] or the {uri-opera-extension}[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 btn:[Allow access to file URLs] toggle.

[NOTE]
====
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* & **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__**``


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


. Step 1
. Step 2
. Step 3

'''

*Ordered, max 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

[#labeled]
=== 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
. Place new images within the doc-susemanager/adoc/images` directory.
. 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]
----

image::books2.jpg[]

image::books2.jpg[Books 2]

.A Bunch of Moldy Books
[#img-books2]
[caption="Figure 1: ",https://www.suse.com/brandcentral/suse/]
image::books2.jpg[Books 2,300,200]

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

=== Links

==== External
----
https://asciidoctor.org - automatic!

https://asciidoctor.org[Asciidoctor]

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

https://asciidoctor.org - automatic!

https://asciidoctor.org[Asciidoctor]

https://github.com/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 xref:#labeled[Labeled] to learn how to use labels.

'''

[#inter-document-cross-refs]
==== 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 xref:filename.adoc#section-id[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]
.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...
====

'''
== 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:

[source, adoc]
--
:draft:

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