SUSE Technical Reference Documentation Contributors' Guide #

SUSE® Technical Reference Documentation (Technical Reference Documentation) is the open collection of contributed, high quality, technical guidance for solutions that address real-world use cases with SUSE, partner, and community components. The Technical Reference Documentation collection is implemented as code, with source files managed and maintained in the Technical Reference Documentation GitHub repository. Both rendered documentation and source code are open source licensed and freely available.

Note

Contributions to SUSE Technical Reference Documentation are expected to meet SUSE’s high standards for quality. However, as voluntary contributions, SUSE makes no guarantee for their accuracy, completeness, or appropriateness for specific situations or environments.

Contributions to Technical Reference Documentation come from SUSE, partners, and the wider community. These are welcome and encouraged. Minor fixes for existing documentation can be submitted easily through the Report an issue links in the HTML version of any document. For a new document, a successful contributor will require deeper familiarity with the SUSE Technical Reference Documentation style, structure, tools, and workflows.

SUSE Technical References are documentation-as-code. They are built from a collection of AsciiDoc and DocBook source files that are rendered into published formats, such as HTML and PDF. Development often begins in a favorite word processor or shared document editing environment, making it easier to contribute content without learning to code. But, ultimately, these documents must be implemented in code.

Those who only intend to contribute content outside the documentation-as-code environment are still encouraged to become familiar with Documentation types and SUSE Documentation Writing style.

Those who will be working in the documentation-as-code environment will need the following:

The three primary types of SUSE Technical References are:

Standard templates for these document types are available as Google Docs, DOCX files, and as the documentation-as-code files.

The source files SUSE Technical Referencess are available in the Technical Reference Documentation source repository, hosted on GitHub. See Repository structure for more information about the repository’s organization and contents.

Contributors use a Git workflow to work with the source repository. This includes the following major steps:

You can find more details on each of these workflow steps in the following sections.

The SUSE Technical Reference Documentation source Git repository is hosted on GitHub to facilitate management and collaboration. A Git repository is a directory or folder in a file system along with metadata and tooling for tracking and managing file revisions. One of your first steps as a contributor is to clone the repository to your local system, where you will edit the source files for your document. Thus, it is helpful to have a general understanding of the repository’s structure and contents.

The top-level directory structure of the Technical Reference Documentation source repository is illustrated in the listing below.

.
├── common 1
├── contributors 2
├── kubernetes 3
├── linux
└── references 4

As a contributor, your efforts will be focused inside the references directory.

references
├── bin -> ../common/bin
...
├── everpure
...
├── jupyter
...
├── hitachi
...
├── kubeflow
...
├── supermicro
...
├── suse
...
├── veeam
...

Here, you find subdirectories that identify the featured technology partner or community project. For example, the source files for a reference featuring JupyterHub, which is part of Project Jupyter, would be found in the jupyter directory. If an appropriate directory for your technical references does not already exist, you can create one during the workspace setup process. There is also a suse directory (containing document sources that feature only SUSE components) and a symbolic link to a bin directory (containing helpful scripts for contributors).

Tip

For a technical reference featuring more than one component provider, select only one for the directory name. As a general rule, the selected partner provides the component at the top of the software stack that delivers a unique, highlighted capability. If important, additional component providers can be noted in the names of your source files.

Your work as a contributor is inside a provider directory. The structure and contents of an example provider directory are illustrated below for a simple getting started guide.

provider
├── DC-gs_suse-prod_partner-product 1
├── adoc 2
│   ├── common_docinfo_vars.adoc -> ../../../common/adoc/common_docinfo_vars.adoc 3
│   ├── common_gfdl1.2_i.adoc -> ../../../common/adoc/common_gfdl1.2_i.adoc
│   ├── common_sbp_legal_notice.adoc -> ../../../common/adoc/common_sbp_legal_notice.adoc
│   ├── common_trd_legal_notice.adoc -> ../../../common/adoc/common_trd_legal_notice.adoc
│   ├── gs_suse-prod_partner-product.adoc 4
│   ├── gs_suse-prod_partner-product-docinfo.xml 5
│   └── gs_suse-prod_partner-product-vars.adoc 6
├── images -> media
└── media 7
    └── src
        ├── png
        │   ├──  suse-prod_partner-prod_architecture.png
        │   └──  suse-prod_partner-prod_ui.png
        └── svg
            └── suse.svg -> ../../../../../common/images/src/svg/suse.svg

1	Doc Config (DC) file There is only one DC file per technical reference. It specifies the location of the main content, the stylesheet to use for formatting, the draft state, and more. You typically only need to edit this file once, when you are ready to publish and you turn off draft mode.
2	adoc directory The adoc directory contains content and metadata files, as described below.
3	Common files Your published document automatically includes standard content contained in these symbolically linked files.
4	Main content file Your main content file, in AsciiDoc markup language, is where you add the content you wish to see in the published document.
5	DocBook metadata (docinfo.xml) file The docinfo.xml file provides information about your document. You typically only need to make minor edits to the standard template.
6	Vars file The vars file contains variable (or document attribute) definitions. These include the product names and versions, website and documentation URLs, document title, author names, and more. These variables are then substituted for text in the main content file and DocBook metadata file to ensure consistency throughout your document. Additionally, using variables makes it easier to make future updates, such as if a product name or website URL change.
7	media directory The media directory contains all media files, such as diagrams and screenshots, you wish to appear in your published document. Media files must be organized by file type under media/src. Note Legacy processes referenced an images directory. Today, images is simply a symbolic link to the media directory and is maintained for compatibility.

See Working with source files for more about the contents of your project directory.

SUSE Technical References are rendered from source files maintained on GitHub in the Technical Reference Documentation source repository. You do not work directly with the repository. Instead, you work in your own workspace. This workspace consists of two parts:

These steps are detailed below.

Note

You typically only need to set up your workspace once.

6.1 Forking the Technical Reference Documentation repository #

 

The first step to setting up your workspace is to create a fork of the upstream Technical Reference Documentation source repository into your own GitHub account.

Note

If you work for SUSE or a partner company, you should use your company-sanctioned GitHub account.

Create your fork of the upstream Technical Reference Documentation repository by following the steps detailed below.

1. Open your Web browser and log into your GitHub account.

2. Navigate to the Technical Reference Documentation source repository.

3. Fork this repository into your own account.

   1. In the GitHub UI, click Fork, then + Create a new fork.

      

   2. In the Create a new fork dialog, give your repository a different name to distinguish make it easier to distinguish from upstream and also include a description.

      

   3. Click Create fork.

6.2 Cloning the fork #

 

After creating your fork, you need to clone it on your local system. When you clone a Git repository, you download a full copy of the repository data at that point in time. This includes not just source files but Git metadata, too. Clone your fork by following the steps detailed below.

1. Launch a terminal on your local system.

2. On the command line, change to the directory where you will store the clone, creating it if necessary.

   For example,

   mkdir -p ~/git/GITHUB-USER
   cd ~/git/GITHUB-USER

   where GITHUB-USER is your GitHub username.

   

   Note

   This directory structure is recommended for good housekeeping but is not strictly required.

3. Clone your fork.

   git clone git@github.com:GITHUB-USER/YOUR-REPO-NAME.git

   where YOUR-REPO-NAME is the name you gave to your repository fork.

   

   Tip

   To find the URL of your fork in the GitHub UI:

   1. Log into GitHub and go to your fork.

   2. Click <> Code.

   3. Select the Local tab.

   4. Click SSH.

   5. Click the "copy" icon to copy the URL to your clipboard.

4. Enter the top-level directory of your clone.

   cd YOUR-REPO-NAME

5. Configure the Technical Reference Documentation source repository as your upstream remote.

   git remote add upstream git@github.com:SUSE/technical-reference-documentation.git

   

   Note

   Git uses the concept of remotes to communicate with repositories beyond the clone on your local system. When you created your local clone, your fork on GitHub was assigned the name origin. And, because the Technical Reference Documentation source repository is upstream of your fork, you assign it the name upstream here.

6. Verify your remotes.

   git remote -v

   origin  git@github.com:GITHUB-USER/YOUR-REPO-NAME.git (fetch)
   origin  git@github.com:GITHUB-USER/YOUR-REPO-NAME.git (push)
   upstream        git@github.com:SUSE/technical-reference-documentation.git (fetch)
   upstream        git@github.com:SUSE/technical-reference-documentation.git (push)

Important

Your workspace typically only needs to be set up once, but it must be maintained. Two critical maintenance activities include:

• keeping your workspace up-to-date with the upstream and origin repositories

• trimming branches

These topics are discussed elsewhere in this guide.

When you have your workspace set up, you are ready to start a new documentation project. This involves two main activities:

Details for both activities are providing in the following sections.

Technical Reference Documentation is built from documentation-as-code, contained in source files. Source files provide content, structure, and metadata for your document. No matter where you create your content, it must be encoded in source files within the structure of the Technical Reference Documentation repository.

8.1 Source files #

 

Every technical reference is built or rendered from multiple source files. These include:

• Doc Config (DC) file
  The DC file specifies the location of the main content, the stylesheet to use for formatting, the draft state, and more. There is only one DC file per technical reference, located at the root of your project directory, and its name always begins with DC-. You typically only need to edit this file once, when you are ready to publish and you turn off draft mode.

• DocBook metadata (docinfo) file
  Information about your document is provided by the docinfo file. It is located in your project’s adoc directory, and its file name always ends in -docinfo.xml. The standard template makes heavy use of variables to minimize the edits you must make to this file. Typical edits include updating variable names to match the ones you define in the vars file, identifying additional products or authors, and expanding the revision history.

• Variables (vars) file
  SUSE Technical References make heavy use of variables (or document attributes), most of which are defined in your vars file. Your vars file located in your project’s adoc directory and its file name always ends in -vars.adoc. Using variables helps ensure consistency throughout your document and also simplifies future revisions. The standard template provides stubs for required and recommended variable definitions. One of your first editing tasks is to define the variables you will use in your document.

• Main content file
  Your main content file, located in your project’s adoc directory, is identified in the DC file. This is where you add your main content, formatted with the AsciiDoc markup language. The standard template provide the framework for your selected document type. You can have multiple content files, but they must all be linked (with the AsciiDoc include directive) into your main content file.

• common content files
  These are source files that are included automatically when your document is rendered, providing such things as the open source documentation license and standard disclaimer. The refsetup.sh script creates symbolic links to these common files in your project’s adoc directory, but you do not edit them.

• media files
  In practice, 'media' refers to images that are included in your rendered document. These can include logos (for example, the SUSE logo is automatically included on the cover page), diagrams, screenshots, and so on.

  Many image file types are supported, but preference is given to:

  • Scaled Vector Graphics or 'SVG' is a widely-deployed, royalty-free, vector graphics format developed and maintained by the W3C. A vector graphics image is rendered from a set of instructions that defines the image from basic, geometric shapes. This allows SVGs to be resized without loss of clarity. SVGs are typically used for logos and architectural diagrams. Copy any SVGs you wish to include into your media/src/svg directory.

  • Portable Network Graphics or 'PNG' is a raster graphics format. A raster image encodes information (like position, color, or brightness) for each pixel (picture element) that makes up the image. PNG uses lossless compression, allowing PNGs to be edited and resaved without loss of clarity (unlike Joint Photographic Experts Group or 'JPEG' images). Scaling raster images can introduce artifacts. This is particularly apparent when images are enlarged. Choose image resolutions to minimize these artifacts. Copy any PNGs or JPGs you wish to use into your media/src/png or media/src/jpg directory, respectively.

Tip

Save yourself effort by using the refsetup.sh script to set up your project. See Starting your project for for information.

8.2 Development workflow #

 

However you develop your content, in the end, it must be encoded into source files in the Technical Reference Documentation repository. You may choose to edit source files yourself or share the joy with others. In both cases, it is important to make use of your GitHub fork (origin) to preserve your work, allow for asynchronous collaboration, and submit your completed project.

Note

Recall that, during setup, you established two remotes for your local clone:

• origin: created automatically by the cloning process points to your GitHub fork.

• upstream: added by you to point to the upstream Technical Reference Documentation repository.

While editing locally, it is good practice to keep in sync with your GitHub fork (origin). Do this by:

1. Frequently committing your changes and pushing them to origin, especially at the end of every editing session.

2. Pulling (fetching and merging) any changes from origin at the start of every new editing session.

This workflow is detailed below.

1. Enter the local directory containing the clone of your GitHub fork (origin).

   cd ~/git/GITHUB-USER/YOUR-REPO-NAME/references

2. Check out your project’s branch.

   git checkout my-tuxy-project

   

   Tip

   Always remember to work in your branch. If you make edits in the wrong branch, back out all the changes you made before switching to the correct branch to work on your project.

3. Update the clone from your origin remote.

   This allows you to integrate any edits or other content from your contributors, helping you minimize merge conflicts later.

   git pull origin

   

   Tip

   It is not necessary to specify the origin remote, since it is configured as your default for tracking.

   

   Important

   Be sure to fix any merge errors before proceeding.

4. Create your content.

   A typical content session involves editing source files and copying assets (such as image files) into appropriate project directories. For content style and formatting guidance, see Writing style and AsciiDoc.

5. Render your document with DAPS to verify content, layout, and style.

   

   Note

   You may get validation errors if you have invalid AsciiDoc syntax. You must then find and correct these errors.

6. Commit your changes locally.

   Add new and changed files to the index (staging area).

   git add .

   Commit the contents of the index to the current branch.

   git commit -m "updated section 5; added screenshot"

   

   Tip

   Always include a commit message as a reminder to yourself and to let your collaboration team know what changes you made in this commit.

7. Push the commit to your origin remote.

   git push origin

   

   Note

   The first time you push a commit on your branch, you will see a warning like:

   fatal: The current branch my-tuxy-project has no upstream branch.
   To push the current branch and set the remote as upstream, use
   
       git push --set-upstream origin my-tuxy-project
   
   To have this happen automatically for branches without a tracking
   upstream, see 'push.autoSetupRemote' in 'git help config'.

   Simply follow the instructions to fix the issue.

   You only need to do this once.

8. Repeat these steps until you are finished with all content edits.

   

   Tip

   It is a good idea to break up long content creation sessions by pausing to commit and push edits to your origin remote.

9. Unset the "DRAFT" designation for your documentation project.
   Your document is marked as "DRAFT" by default when using the standard templates. Unset "draft mode" before submitting your document with the following steps:

   1. Edit your DC file.

   2. Locate the line containing "DRAFT=yes" and prefix it with a hash mark ('#').
      That is,

      #DRAFT=yes

With your content complete and no longer marked as "DRAFT," you can proceed to Submitting your project.

You submit your project for inclusion in the Technical Reference Documentation with a Git pull request (PR). A PR is a request to merge the changes contained in one branch into another branch of a Git repository. In your case, your PR will request to merge the changes in your project branch into the 'main' branch of the upstream Technical Reference Documentation repository.

Technical Reference Documentation is part of the SUSE Documentation ecosystem. Its objective is to provide well-structured, clear, and concise technical information in a way that facilitates real-world problem-solving. Consistent writing style and formatting contribute to the creation of high quality documentation.

Writing style goes beyond the essential elements of spelling, grammar, and punctuation to include tone of voice, choice of words, sentence and paragraph structure, and more.

Keep in mind the following general writing style guidance as you create content for Technical Reference Documentation:

Explore more about writing style in the SUSE Documentation Style Guide.

Technical Reference Documentation uses AsciiDoc for content formatting and structure. AsciiDoc is a lightweight and semantic markup language. It has an intuitive syntax and is designed for technical writing.

This section provides an introduction to various aspects of AsciiDoc with examples to help you get started.

For additional reference, see:

ADD TOC HERE

11.4 Document attributes and variables #

 

In AsciiDoc, document attributes are name-value pairs that you can use to configure the AsciiDoc processor, define document metadata, and create reusable content. Think of document attributes as document-scoped variables. They can be defined anywhere in your document and used from that point forward as you would variables in other programming languages.

Tip

For best practice, define all variables in one place (your vars file).

Using the standard templates, your vars file is imported at the beginning of your main content file. This ensures that these variables have document-wide scope.

A variable definition has the form:

:name-of-an-attribute: value of the attribute

The definition begins with the variable name surrounded by colons ( : ) and is followed by a space and the value that is to be assigned. The value then includes everything between the space and the newline character.

Tip

Some variable definition stubs are provided in the vars file template. If you modify the provided variable names, be sure to modify them everywhere they are referenced. This may include your main content file, your docinfo file, and even later in your vars file.

Some example variable definitions are shown below.

:srancher-brand: SUSE® Rancher Prime
:srancher-long: SUSE Rancher Prime
:srancher: SUSE Rancher
:srancher-version1: 2.13
:srancher-website: https://www.suse.com/products/rancher/
:srancher-docs: https://documentation.suse.com/cloudnative/rancher-manager/latest/en/
:srancher-docs-ports: {srancher-docs}installation-and-upgrade/requirements/port-requirements.html
:doctitle: Enterprise AI on {srancher-long}

Tip

It is a good practice to use variables for various aspects of the products featured in your technical reference. This helps you maintain consistency, minimize typing errors, and streamline future updates.

After defining a variable, you can reference it by surrounding the variable name with curly braces ( { and } ). You can even define new variables with references to already-defined variables (see the srancher-docs-ports and doctitle variables in the previous example).

:doctitle: {svirt-long} and {xbackup-long}
:docsubtitle: Implement Disaster Recovery for your Cloud Native Virtualization Environment

= {doctitle}: {docsubtitle}

<title>{doctitle}</title>
<subtitle>{docsubtitle}</subtitle>

11.6 Sections #

 

Sections help you group and organize related text.

Start a new section with a section header, designated by two or more equal signs.

For example:

== Section title level 1

=== Section title level 2

==== Section title level 3

Use the following guidance for section headings:

• Choose a section title that clearly identifies what contents to expect.

• If the section focuses on actions, begin with a verbal noun (gerund) or an imperative verb.

  For example:

  == Preparing the cluster
  
  or
  
  == Prepare the cluster

• Use sentence case.
  Only the first word and proper nouns should be capitalized.

• Minimize heading length.
  1 to 4 words should be sufficient.

• Avoid using more than three (====) section levels.

• Ensure all sections have content.
  A subsection heading should never immediately follow a section heading without some intervening text.

Consider the following example:

== Enabling Podman

Podman, which is short for Pod Manager, is a daemonless, open source tool ...


=== Installing the Podman package

If Podman is not already installed, you can install it with `zypper` ...


=== Configuring Podman

By default, only the root user can run Podman containers.
You can enable non-privileged users to use Podman by ...


== Using Podman

This section provides an overview of a typical Podman workflow.

=== Creating a build directory

You need a place in your file system to contain ...

Tip

Every section header automatically becomes a cross reference. This lets you create an internal link to a section from anywhere within your document.

To do this, simply use the text of the section header enclosed in double angle brackets ( << and >> ).

For example:

Learn more about <<Configuring Podman>>.

The `manifest.yaml` file is located in the `$HOME/my-tuxy-project` directory.

11.9 Admonitions #

 

Use admonitions to help draw the reader’s attention to content. AsciiDoc supports five admonition types represented by the following labels:

• NOTE: Provides additional information.

• TIP: Suggests helpful guidance.

• IMPORTANT: Highlights an important point.

• CAUTION: Advises that care should be taken.

• WARNING: Informs of danger, harm, or consequences.

The basic admonition style places the admonition label followed by a colon ( : ) at the beginning of a line of text. This is useful for short admonitions that do not contain a line break. For example:

TIP: By default, some `zypper` commands perform `refresh` automatically.

This renders as:

Tip

By default, some zypper commands perform refresh automatically.

The block admonition style is preferred, as it provides more flexibility for the content. The following example illustrates a block admonition:

[IMPORTANT]
====
When working with snapshots to restore data, it is important to know
that there are two fundamentally different scenarios Snapper can handle:

Undoing changes::
When undoing changes as described in the following, two snapshots are
being compared and the changes between these two snapshots are made undone.
Using this method also allows to explicitly select the files that should be
restored.

Rollback::
When doing rollbacks as described in <<System rollback>>, the system is
reset to the state at which the snapshot was taken.
====

11.10 Verbatim and source blocks #

 

Technical guides often need to present source code, commands, and console output as they appear in a code editor or on the console screen. This usually means rendering content with a fixed-width font to preserve spacing and structure. For source code, it also may involve syntax highlighting with color or other text styles.

11.10.1 Listing blocks #

 

The basic listing block is used to denote text that should be rendered verbatim. This is most often used to present output from a command issued in a command-line terminal, or just to present specifically-spaced text.

[listing]
----
The spacing      of       this text      must be       preserved.

      00   01   02   03   04   05
      01   02   03   04   05   00
      02   03   04   05   00   01

drwxr-xr-x 1 geeko geeko 1.3K May 27 16:04 adoc
drwxr-xr-x 1 geeko geeko   86 Apr 30 15:28 build
-rw-r--r-- 1 geeko geeko  963 Jan 22  2025 DC-suse-trd_contrib-guide
lrwxrwxrwx 1 geeko geeko    5 Jun  7  2023 images -> media
drwxr-xr-x 1 geeko geeko    6 Jun  7  2023 media
-rw-r--r-- 1 geeko geeko  546 Jan 22  2025 README.md
----

11.10.2 Source code blocks #

 

A source code block (or source block) is a special version of a listing block that enables syntax highlighting, using color and text styles to distinguish code structures (such as keywords, variables, constants, comments, and so on).

A snippet of Python code is illustrated below.

[source, python]
----
# import libraries
import matplotlib.pyplot as plt
import numpy as np

# define data points
xpoints = np.array([1, 2, 5, 12])
ypoints = np.array([5, 3, 11, 6])

plt.plot(xpoints, ypoints)
plt.show()
----

The key elements of the source block are:

• the explicit block style and language designation ([source, python])
  The style designation identifies the block as a verbatim block containing source code in the specified programming language.
  Some common source language identifiers are: bash, c, html, python, sql, yaml, and xml.

• the delimiter (----)
  The delimiter marks the start and the end of the block content.

11.10.3 Commands #

 

There are two ways to handle commands: inline and as a source block.

Short commands can be identified inline with other text by delimiting the command with the backtick character ( ` ), as shown below.

The `zypper` command can be used to install, update, or remove software, manage software repositories, perform queries, and more.

For full command examples, the best practice is to use a source block with console as the language identifier.

For example:

[source, console]
----
sudo zypper install vim
----

In Technical Reference Documentation, it is common to combine a command-line instruction with the resulting output. This is illustrated below.

. Learn more about the `vim` package by issuing the following command:
+
[source, console]
----
zypper info vim
----
+
[listing]
----
Information for package vim:
----------------------------
Repository     : Main Repository (OSS)
Name           : vim
Version        : 9.2.0219-1.1
Arch           : x86_64
Vendor         : openSUSE
Installed Size : 5.2 MiB
Installed      : Yes (automatically)
Status         : out-of-date (version 9.2.0010-1.1 installed)
Source package : vim-9.2.0219-1.1.src
Upstream URL   : https://www.vim.org/
Summary        : Vi IMproved
Description    :
    Vim (Vi IMproved) is an almost compatible version of the UNIX editor
    vi. Almost every possible command can be performed using only ASCII
    characters. Only the 'Q' command is missing (you do not need it). Many
    new features have been added: multilevel undo, command line history,
    file name completion, block operations, and editing of binary data.
----

Important

In this example, the plus symbol ( + ) is used to connect these blocks to the list item and preserve indentation.

See Continuation for more on this topic.

11.10.4 Attribute substitutions #

 

Imagine that you need to illustrate several commands that reference the same, long, and complex argument, such as a file name. Each time you type the argument, you risk making a typo.

This is a perfect use for a variable (document attribute), but listing and source blocks are verbatim. So, variable references inside the blocks are ignored by default. To overcome this, you can use the subs="attributes+" block attribute.

Consider this simple example:

In your vars file, define a variable:

// attribute in your vars file
:myPath: /home/geeko/myproject/

In your main content file, reference the variable inside a source block as follows:

// attribute referenced in source code block
[source, console, subs="attributes+"]
----

tree {myPath}

----

By including subs="attributes+", this is rendered as:

tree /home/geeko/myproject/

Caution

Attribute substitution can be tricky.

For example, the Bash shell also uses curly braces in referencing variables (such as, ${PATH}). With subs="attributes+" in your block designation, the rendering engine treats any "words" surrounded by curly braces as AsciiDoc variables and tries to render them.

Consider the following example:

Determine your current display server type by issuing the following command:

[source, console, subs="attributes+"]
----
echo ${XDG_SESSION_TYPE}
----

Your goal is to display this command verbatim, but the rendering engine tries to find an AsciiDoc definition for XDG_SESSION_TYPE. If it finds one, it substitutes the value. If it does not find one, the rendering fails. Neither result is what you want.

When you want verbatim interpretation, the best practice is not to use the subs="attributes+" option.

If you do need some substitutions but not others, you can use escaping to let the rendering engine know your intentions. By simply placing a backslash ( \ ) just before each of the curly braces, you designate the curly brace as a literal character.

Here is an example:

:myPrompt: geeko@mangrove.lane:~/myproject:

[source, console, subs="attributes+"]
----

{myPrompt} echo "My stored value is in the variable, $\{myVariable\}."

----

This source block renders as:

geeko@mangrove.lane:~/myproject: echo "My stored value is in the variable, ${myVariable}."

For more on substitutions, see Asciidoctor Docs: Customize the Substitutions Applied to Blocks.

. Open `myfile.txt`.

.. Click __File__ > __Open__.

.. Select `myfile.txt` from the list.

.. Click __Open__.

11.12 Links #

 

AsciiDoc allows you to provide clickable links to external, addressable resources in your documents.

A link consists of two parts:

target

This is the external resource and is represented by an address, known as a Uniform Resource Identifier (URI). A common type of URI is the familiar Uniform Resource Locator (URL) or address of a Web page.

link text

This is the text you wish the reader to see (typically in place of the URI) and be able to click to open the remote resource in an appropriate application (such as a Web browser).

The AsciiDoc rendering engine detects common URL protocols, including HTTP, HTTPS, FTP, IRC, and MAILTO. These are then rendered as a clickable link with the URL itself as the link text.

For best practices, use custom link text in place of the URL. To do this, append the URL with the desired text enclosed in square brackets ([ and ]).

For example:

Manage your subscriptions and support cases at the https://scc.suse.com[SUSE Customer Center].

This is rendered as:

Manage your subscriptions and support cases at the SUSE Customer Center.

Tip

You can minimize typos and simplify future updates by using variables in your links.

Start by defining the variables you need in your vars file:

:scc: SUSE Customer Center
:scc-url: https://scc.suse.com

Then, reference them in your content file:

Manage your subscriptions and support cases at the {scc-url}[{scc}].

image::TARGET[ATTRIBUTES]

image::tuxy-ui-dashboard.png[title="Tuxy UI Dashboard", Tuxy UI Dashboard, scaledwidth="75%", align="center"]

11.14 Continuation #

 

Continuation is a useful technique for "attaching" one block element to another.

The need for continuation arises most often in lists. Consider the following example:

. Log your system's current uptime to the file, `my-uptime.log`.
[source, console]
----
uptime | tee -a uptime.log
----

This is rendered as:

1. Log your system’s current uptime to the file, my-uptime.log.

uptime | tee -a my-uptime.log

Even though there is no empty line between the list element and the command, the command is not properly aligned with the list element.

Continuation allows you to fix this by simply inserting a plus sign ( + ) between the list item text and the source code block, as follows:

. Log your system's current uptime to the file, `my-uptime.log`.
+
[source, console]
----
uptime | tee -a my-uptime.log
----

Now, this renders as:

1. Log your system’s current uptime to the file, my-uptime.log.

   uptime | tee -a my-uptime.log

You can proceed to "continue" that same list item with as many block elements as required. For example:

. Log your system's current uptime to the file, `my-uptime.log`.
+
[source, console]
----
uptime | tee -a my-uptime.log
----
You should see output like:
+
[listing]
----
16:54:54  up   8:23,  2 users,  load average: 0.47, 0.48, 0.48
----
+
[TIP]
====
The `-a` option tells `tee` to append the output to the end of the file.
====

. Verify that the time was written to the end of the log.
+
[source, console]
----
tail -1 my-uptime.log
----
+
[listing]
----
16:54:54  up   8:23,  2 users,  load average: 0.47, 0.48, 0.48
----

This is now properly rendered as:

1. Log your system’s current uptime to the file, my-uptime.log.

   uptime | tee -a my-uptime.log

   You should see output like:

   16:54:54  up   8:23,  2 users,  load average: 0.47, 0.48, 0.48

   

   Tip

   The -a option tells tee to append the output to the end of the file.

2. Verify that the time was written to the end of the log.

   tail -1 my-uptime.log

   16:54:54  up   8:23,  2 users,  load average: 0.47, 0.48, 0.48

Caution

Use continuation with caution. Improper use of continuation can produce unexpected results and be difficult to debug.

SUSE Technical Reference Documentation is a repository of high quality documentation for solutions that address real-world use cases with featured SUSE, partner, and community components.

This document provides an overview of the tools, techniques, workflows, and styles that you will use to make successful contributions to Technical Reference Documentation.

Copyright © 2006–2026 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled "GNU Free Documentation License".

SUSE, the SUSE logo and YaST are registered trademarks of SUSE LLC in the United States and other countries. For SUSE trademarks, see https://www.suse.com/company/legal/.

Linux is a registered trademark of Linus Torvalds. All other names or trademarks mentioned in this document may be trademarks or registered trademarks of their respective owners.

Documents published as part of the series SUSE Technical Reference Documentation have been contributed voluntarily by SUSE employees and third parties. They are meant to serve as examples of how particular actions can be performed. They have been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. SUSE cannot verify that actions described in these documents do what is claimed or whether actions described have unintended consequences. SUSE LLC, its affiliates, the authors, and the translators may not be held liable for possible errors or the consequences thereof.

Copyright © 2000, 2001, 2002 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties—​for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

Copyright (c) YEAR YOUR NAME.
   Permission is granted to copy, distribute and/or modify this document
   under the terms of the GNU Free Documentation License, Version 1.2
   or any later version published by the Free Software Foundation;
   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
   A copy of the license is included in the section entitled “GNU
   Free Documentation License”.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “ with…​Texts.” line with this:

with the Invariant Sections being LIST THEIR TITLES, with the
   Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.