Rules of thumb

Add the following lines to the main document:

ifdef::env-github,env-browser[:outfilesuffix: .adoc]
:rootdir: .
:imagesdir: {rootdir}/images
:toclevels: 2
:toc:
:numbered:

Add the following lines to every other asciidoc document:

ifdef::env-github,env-browser[:outfilesuffix: .adoc]
ifndef::rootdir[:rootdir: ../]
:imagesdir: {rootdir}/images

Note: You should update the actual directories in the snippets above to be consistent with your project!

Some details

Automatic section-depth for included files Section levels can be altered with the following syntax:

• :leveloffset: 3

This will modify all section levels under the command. To return to the original offset, you have to explicitly specify

• :leveloffset: 0

Relative level offsets also can be used:

• :leveloffset: +1 and :leveloffset: -1

Offsets can be limited to single includes:

• include::filename.adoc[leveloffset=+1]

Images Images can be included with the following syntax:

• image::image.png[]

Images can have captions, referable identifiers, alt text, and many more options:

[identifier](/FTSRG/cheat-sheets/wiki/identifier)
.caption title
image::image.png[alt text]

Image paths are calculated relative to the current directory by default, but the default image directory can be set for each file separately, by including the following line:

• :imagesdir: ./path/to/images

When generating output for a document, the working directory is set to the containing directory, which will be different when transforming the main documentation file, and rendering single pages on Github. This will mess up the relative paths when inserting images. A workaround is to set manually a root directory attribute in the following way:

• add :rootdir: ./ to the main file of the documentation
• add ifndef::rootdir[:rootdir: ../] to every other file
• You have to specify the root directory relative to the edited file instead of using ./ and ../
• set the image directory with :imagesdir: {rootdir}/images in every file

References and ids Section and block ids: Referable ids can be added to elements by adding the following line before the element:

• [block_id](/FTSRG/cheat-sheets/wiki/block_id)

Asciidoc also provides ids for sections, but the Github renderer and Asciidoctor works differently, thus using these automatic ids are not advised:

• Asciidoctor: ==This is a section --> _this_is_a_section
• Github: ==This is a section --> this-is-a-section

References inside a single file can be added with

• <<SectionId, link text>>

Cross-references between files can be added with

• <<filename#, link text>>
• <<filename#SectionId, link text>>
• <<path/to/file/filename#SectionId, link text>>

By default, the asciidoc renderers convert the filename part "smartly". If it refers to an included file, the filename is omitted, and the reference becomes a simple intra-file reference. If the file is not included in the output, the filename is transformed into filename.outputformat (e.g. filename.html). However this can cause problems on Github, where the document is rendered to html, but the output is accessed at the repoURL/path/filename.asciidoc page - resulting in broken links. To fix this issue, the following line should be added to all document files:

• ifdef::env-github,env-browser[:outfilesuffix: .asciidoc]

Links to other resources Links to other resources (e.g. webpages) can be added with the following syntax. The URLs of these links are never modified during rendering.

• link:url[optional link text, optional target attribute, optional role attribute]

Asciidoc can recognize standard urls (e.g. http://, ftp:://, mailto:) in the text, these are automatically converted into links.

Note This summary assumes that the documents on Github are stored in a standard repository, not in a Github wiki. Using a standard repository is advised because it provides in-file search, correctly handles files in directory hierarchies, supports both .adoc and .asciidoc file extensions, supports online editing, and provides "preview" just like the wiki.

See the Asciidoctor documentation for detailed syntax description and for syntax quick reference.

PDF style PDF export can use styles defined in yml format, see its github page for details