Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
documentation.suse.com / SUSE Documentation Style Guide / Working with AsciiDoc
Applies to 2024-10

11 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.