Useful AsciiDoc Snippets

AsciiDoc

AsciiDoc is a text document format for writing notes, documentation, articles, books, e-books, slideshows, web pages, and blogs. AsciiDoc belongs to the family of lightweight markup languages, the most renowned of which is Markdown. AsciiDoc stands out from this group because it supports all the structural elements necessary for drafting articles and technical manuals. AsciiDoc is easy to write and easy to read (in raw form). It’s also easy to proof and edit.

Page references

Syntax :

xref::version@component:module:folder/page-name.adoc#fragment[Alt text]

Syntax

Description

xref

Prefix macro

version@

Name of the version. The value is defined in the antora-playbook.yml file.

component

Name of the destination component followed directly by a colon(:)

module

Name of the destination module followed directly by a colon(:)

folder

Optional field to use only if the page is in different folder.

page-name.adoc

Specify the local path of the destination file relative to the module’s documents directory which you want to reference.

#fragment

An anchor point to link to in the destination page(deep link). This field is optional.

  • Reference the page in the same folder

    xref:partitions.adoc[Partitions in Discovery]

  • Reference the page in the different folder

    xref:ondemand/active-jobs.adoc[Active Jobs]

  • Reference the page in the different module

    xref:module-name:page-name.adoc[Link Text]

  • Reference the page in the different component

    xref:component-name:module-name:page-name.adoc[Link Text]

  • Reference the page in the ROOT module of a different component

    xref:component-name::page-name.adoc[Link Text]

    You don’t need to specify any version, component name or module name while referencing the page in the same module under same component.

Using Partials

Partials are files which contain reusable snippets of content. Partials are stored under the partials directory under the same module. Partials and the page where it’s used are usually stored in the same module. However, the partials can be used in any pages in the documentation.

Syntax :

 include::version@component:module:partial$name-of-file.adoc[optional attributes]

Syntax

Description

include

Directive

version

Name of the version. The value is defined in the antora-playbook.yml file.

component

Name of the destination component followed directly by a colon(:)

module

Name of the destination module followed directly by a colon(:)

partial$

keyword

name-of-file.adoc

Partial filename

[optional attributes]

level offset & tags

  • Include a partial from the same module

     include::partial$login.adoc[]

    If the partial file to be included in the page belongs to the same module, simply type the include directive followed by (::), and then partial$ followed by the partial filename.

  • Include a partial from different module

     include::module-name:partial$login.adoc[]

    If the partials to be included in the page is present in a different module under the same component, use the above command.

  • Include a partial from another component

     include::component-name::partial$login.adoc[]

    When the partial file and the page file belongs to different components, enter the partial’s component followed by the module, partial$ and the partial filename. If you don’t specify any version, it renders the latest stable version of the component. If you want a particular version, include the version before the component name. Also, if the component name is present and the module is ROOT, you can leave the module name field blank. That’s the reason the component name is followed by (::)

     include::1.0@component-name::partial$login.adoc[]

    It includes the partial file in the page for the component version 1.0.

Add an image

Syntax :

image::relative-path-to-image-file[optional alt text]

Example :

image::ondemand/ood-desktop-launch.png[Launch Desktop]

In the above example, ood-desktop-launch.png is in the path images/ondemand/ood-desktop-launch.png. Specify the local path of the image file relative to the module’s images directory which you want to include in the page.

A module’s image files must be stored in the images folder.

Other useful snippets

Include Emojis

To include an emoji in the documentation, use the below syntax point_down

 emoji:emoji-name[]

Example :

 emoji:lock[]

Output: lock

Include Section Headings

Sections partition a page into a content hierarchy and are defined using section titles.

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

====== Level 5 Section Title (maximum level depth)

Adding tabs

Syntax to create tabs in the docs.

[tabs]
====

Title A::
+
--
Description about Title A
--

Title B::
+
--
Description about Title B
--
====

Output

  • Title A

  • Title B

Description about Title A

Description about Title B

For more information on how these tabs block are integrated into the HPC website, please refer to → Asciidoctor Tabs Block Integration.