SUSE AI Product Documentation

Welcome to the SUSE AI product documentation repository.

Asciidoctor vs Markdown

• Comparison by example

Asciidoctor resources

Official documentation::

• Quick reference

• Getting Started

• Cheat sheet

• Asciidoc language documentation

• Inline elements

• Block elements

Editing & Previewing

The documentation is written in Asciidoc(tor). Start with a very basic template.adoc[Template].

• Sources can be directly edited and previewed in GitHub.

• If you edit your docs locally

  • Preview add-ons for Web browsers

  • IDEs and text editors

  • There also is asciidoc modes for emacs and vi ;-)

Best practices

One sentence per line

• make editing directly in GitHub a lot easier and makes the sources better readable

• use soft wrap in your editor

Headlines must be in order

• always start a document with headline level 0

  • only use a single level zero headline

• it is not allowed to skip a level with subsequent headlines

= Level 0

== Level 1

=== Level 2

// ===== Level 4: Not allowed

==== Level 3

== Level 1

Do not use automatic IDs

Asciidoctor automatically generates IDs/anchors to which you can link to:

Do not use

== Usage
...

Refer to xref:usage[] for more information.

It is not recommended using this feature, because every time you change the respective headline, you would need to change the reference(s), too. Rather use explicit IDs/anchors:

Do use

[#usage]
== Usage
...

Refer to xref:usage[] for more information.

Always use block delimiters

Some block elements can be written in a short and a long form. Always use the long form to avoid confusion and to increase the readability of the sources.

Do not use

NOTE: This is a note

 This is a literal block

Do use

[NOTE]
====
This is a note
====

....
This is a literal block
....

Nested structures

Nested structures, e.g. an annotation inside a list item, must be concatenated by a plus (+) character.

* normal listitem
* lisitem with annotation
+
[NOTE]
====
note
====
+
* lisitem with two paragraphs
+
second paragraph
+
* normal listitem

Keystrokes, Menus, Buttons

Asciidoctor comes with three macros for displaying keystrokes, menu-selection and button-clicks:

Press kbd:[C] to continue or kbd:[Crtl+C] to cancel, kbd:[F1] opens the help menu.

To save the file, select menu:File[Save].
Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.

Press the btn:[OK] button when you are finished.

❗	This feature is only activated when the attribute :experimental: is set in the header.

Tabbed view

Use delimited/labeled lists preceded by [.tabs]:

[.tabs]
TAB 1::
+
Content tab 1
+
TAB 2::
+
Content tab 2

Include statements must be separated by empty lines

Always make sure that an include statement is preceded and followed by an empty line.

Unsupported Asciidoc tags

The following is not supported when creating a SUSE branded version. Do not use:

• highlight, underline, strikethrough

  #highlight#
  ##high##light
  [.underline]#underline#
  [.line-through]#strike-through#

• checklists

  * [*] checked
  * [x] also checked
  * [ ] not checked

• audio and video

  audio::audio.wav[]
  video:: video.mp4[]

• sidebars

  ****
  Sidebar text
  ****

• footnotes

  footnote:[Footnote]

Building the Documentation

Building a generic version

Building the book in a non-SUSE branded version is easier and quicker than building the SUSE branded version.

Browser extension (the easiest way)

• Install a browser extension to preview asiidoc files in your browser.

• The preview automatically updates on saved change

A local HTML build

• Install asciidoctor on your system.

• Run the following command in the GitHub checkout.

  asciidoctor -d book --attribute="toc=left" <PATH/TO/FILE.adoc>

• Result: PATH/TO/FILE.html

Building the SUSE branded version locally

To build the documentation locally in the format it will get published, use daps2docker Note that doing these builds is not needed to check your contributions. As long as your document renders fine in previews you are good.

Requirements

• make sure your workstation is running docker or podman

• make sure your user can start containers

• install daps2docker from https://download.opensuse.org/repositories/Documentation:/Tools/

• navigate to the local checkout of this repository into the documentation directory

  Building HTML

  daps2docker DC-<FILE> html

  Building Single HTML

  daps2docker DC-<FILE> single-html

  Building PDF

  daps2docker DC-<FILE> pdf

💡	Using Podman By default, daps2docker uses docker as its container engine. To use Podman, export the environment variable CONTAINER_ENGINE=podman: export CONTAINER_ENGINE=podman

💡

Build errors daps2docker builds documentation from DocBook XML sources. Asciidoctor comes with a built-in converter to DocBook. Asciidoc(tor) is way more forgiving than DocBook when it comes to validation. In some cases, valid asciidoc source code does not validate when converting it to DocBook. In such a case building with daps2docker will fail. If that happens, contact me (@fsundermeyer) and I will help.

For more information

…​see the daps2docker repository. You will also find instructions on how to install it on other distributions and how to set a custom configuration.