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.

Refer this for more information AsciiDoc User Guide offical doc

Page references

 xref::version@component:module:folder/page-name.adoc#fragment[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.

 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::Lenovo/-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 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)

Include Tables

[cols="e,m,^,>s",width="25%"]
|============================
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|============================

ex:

1

2

3

4

5

6

7

8

9

10

 
    |===
    ^|0 3+^|1
    ^|0 3+^| 1
    ^|0 3+^| 1
    ^|0  ^| 1  >| 0 ^| 4
    ^|0  ^| 1  <| 0  ^| 1
    |===
---

0

1

0

1

0

1

0

1

0

1

0

1

0

1

 
    |===
    4+^|1
    ^| 0 3+^| 1
    .6+<.>m| 1 2+^.^| 1 ^| 2
    ^| 0 ^| 1 .5+<.>m| 2 ^| 3
    ^| 0 ^| 1 ^| 2 ^| u
    ^| 0 ^| 1 ^| 2 ^|
    ^| 0 2+^|1
    ^| 3+^|1
    |===
---

table figure shown below.

1

0

1

0

1

2

0

1

2

3

0

1

2

u

0

1

2

0

1

1

quote and verse paragraph styles

The optional attribution and citetitle attributes (positional attributes 2 and 3) specify the author and source respectively.

The verse style retains the line breaks, for example:

To see a world in a grain of sand,
And a heaven in a wild flower,
Hold infinity in the palm of your hand,
And eternity in an hour.
— William Blake
from Auguries of Innocence

Admonition Paragraphs

TIP, NOTE, IMPORTANT, WARNING and CAUTION admonishment paragraph styles are generated by placing NOTE:, TIP:, IMPORTANT:, WARNING: or CAUTION: as the first word of the paragraph. For example:

---
NOTE: This is an example note.
or
[NOTE]
This is an example note.

Output

This is an example note.
This is an example note.
Cell 1 Cell 2