This is a draft document that was built and uploaded automatically. It may document beta software and be incomplete or even incorrect. Use this document at your own risk.

Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
SUSE Documentation Style Guide (AsciiDoc) / Working with AsciiDoc
Applies to 2025-09

1 Working with AsciiDoc

 

To create documentation in the AsciiDoc format, adhere to the comprehensive guide at https://asciidoctor.org/docs/asciidoc-recommended-practices.

We also recommend the guidance on AsciiDoc provided in the SUSE Technical Reference Documentation Contributors Guide.

The following things are important when working with AsciiDoc:

  • Only use formatting that is supported by the AsciiDoctor tool. Ignore features that are only documented for the outdated asciidoc (Python) tool. In particular, ignore the documentation at https://powerman.name.

  • Most recommendations from https://github.com/SUSE/doc-susemanager/wiki/markup-syntax are applicable generally. Some recommendations, however, are specific to SUSE Manager documentation, in particular:

    • The section Images—images need to be added the same way they are added in other DAPS-based documentation, under the images/src/FORMAT directory of the repo.

    • The section Working with Drafts—there is currently no equivalent standard functionality.