Asciidoc getting started
Joseph Cayouette v1.0, 2018-05-03
|
🔥
|
This page is out of date! |
This document provides commonly used asciidoc syntax examples.
SUSE Manager documentation can be found here:
|
❗
|
We treat documentation as code (branch, fix, pull request, review merge) |
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: |
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:
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.
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 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!
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
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
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
-
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]
https://asciidoctor.org - automatic! https://asciidoctor.org[Asciidoctor] https://github.com/asciidoctor[Asciidoctor @ *GitHub*]
link:https://asciidoctor.org - automatic!
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.
Our references must always provide the full path including bookname. This prevents errors during pdf construction.
Refer to xref:bookname:filename.adoc#section-id[Link Text] for more information. xref:installation-and-upgrade:proxy-container-setup.adoc[]
See you when you get back from Link Text.
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… |
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...
[[ref-caution-ensure-that]] [CAUTION] .Caution Admonition ==== Ensure that... ====
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::[]