Writing toolkit

For most of you contributing to Magnolia documentation, using plain text and some basic asciidoc suffices. However, it is still nice to have a place to refer to commonly-used asciidoc syntax within the documentation site as well as some of the more unique features we have developed specifically for our setup.

This page contains

If you see something you need to use, just copy it directly from this page and into your text editor.

Basic asciidoc

Write text

Source

Writing text is simple. Plain text is all you need.

Write in *bold*.

Write with _italics_.

Output

Writing text is simple. Plain text is all you need.

Write in bold.

Write with italics.


Level headings

Source

= Level Heading 1

This is used as the title or start of the page.

== Level Heading 2

This begins your section headings.

=== Leading Heading 3

You get the point.

Output

All the headings on this page. For example Level headings.


Lists

See Asciidoctor’s lists for all possible options and more in-depth information.

Source

Unordered (bullets)
* I am
* an unordered list
Ordered
. I am
. an ordered list

Output

  • I am

  • an unordered list


  1. I am

  2. an ordered list


The link: call should be used for URLs outside of the documentation site. Cross references should be used for pages internal to the documentation site. See Cross references for more info on that.

Source

Straight-forward link
link:https://www.magnolia-cms.com/[Magnolia^]
Link with variable/attribute
link:{jira}MOTION-163[MOTION-163^]

Cross references

Cross references should be used for linking pages that are part of the documentation site. To link to an external URL, use Links.

There are two types of cross references

Same page

Source
See <<Write text>> for a quick intro on writing with asciidoc. (1)
1 <<cross-ref>> is the basic syntax. Optionally pass a label like <<cross-ref,label>>.

Output

See Write text for a quick intro on writing with asciidoc.


Documentation site

Antora site-based cross references are vital for navigation purposes around the antora site.

To "future-proof" your cross reference, we recommend using the long-form as shown in numbers 2 and 3 below.

Source
* xref:Releases.adoc[] (1)
* xref:product-docs:ROOT:Releases.adoc[] (2)
* xref:3.x@magnolia-cli:ROOT:index.adoc[] (3)
* See the latest xref:Releases.adoc[release] for more information. (4)
1 Specify the path to the file in the content repo. This is from within the same component and module.
2 Reference the same page from a different component or module. If there are multiple versions, this links to the latest page.
Here product-docs is the component, ROOT is the module, and index.adoc is the page.
3 Link to a specific version of a page.
Here 2.x is the version, magnolia-cli is the component, ROOT is the module, and index.adoc is the page.
4 Pass a label to fit your sentence structure.
Output


Images

Where would we be without visuals, am I right? Inserting images in asciidoc is about as easy as it gets.

Ensure you put the correct path from the images directory. Images are stored in images in the root of the associated repository where you are contributing.

Source

Block image
image::apps/ui-apps-configuration-server-version-index.png[role="zoom"] (1)
1 Adding the role=zoom option allows users to enlarge the image.
Inline image
image:apps/ui-apps-configuration.png[]

Output

Block image
ui apps configuration server version index
Inline image

ui apps configuration


Standard admonition blocks

Admonition blocks help you highlight information and make sure that information stands out from the standard paragraph text.

The fun examples below are directly from the antora site.
NOTE: If you go into the basement, see if you can find Kenny's parka. (1)

TIP: After someone sticks a fork in a socket, reset the circuit in the scary basement. (2)

CAUTION: Don't stick forks in electric sockets. (3)

WARNING: Never go into the basement. (4)

IMPORTANT: A monster lives in the basement. (5)
1 Tells you information that is good to know.
2 Gives you helpful information but it’s not essential.
3 Lets you know to proceed with caution.
4 Lets you know that doing something here might break something else.
5 Important information, but sure go ahead and use your own intuition/intellect on it.

Output

If you go into the basement, see if you can find Kenny’s parka.
After someone sticks a fork in a socket, you’ll need to reset the circuit in the breaker box in the dark and scary basement.
Don’t stick forks in electric sockets.
Never go into the basement.
A monster lives in the basement.


Advanced asciidoc

Partials

Partials are reusable asciidoc pages. Typically, a partial should act as standalone content that when put together with other partials, create an assembly of information in a user story.

For an example partial usage, see Include directives.

Create a partial

To create a partial:

  1. Navigate to the partials directory in the repository in which your working.

  2. Choose an appropriate topic folder for the partial. For example, if the topic is cloud, create the parital in the cloud folder.

  3. Create a new file and name it according to the following pattern:

    1. Concept: conceptual information that describes what something is.

    2. Procedure: procedural information that instructs the user on some task.

    3. Reference: reference information such as parameters or fields.

If you’re not 100% sure, contact someone on the doc team.

Include directives

Include directives allow you to include other asciidoc files in a container page. This adheres to a modular documentation approach and allows the files to be used in multiple container pages where only one source needs to be updated.

Though you technically can include asciidoc files from the pages directory in other pages as an include directive, it’s best practice to include partials only.

Source

include::partial$reference/example-test-include.adoc[leveloffset=+3] (1)
1 The partial$ portion of this directive calls the partial directory (where most include files reside). The reference/ refers to the directory and example-test-include.adoc is the page asciidoc file itself. leveloffset=+3 offsets the base heading level by three levels.

When writing partials, it’s best to make them standalone files. Because of this, start the partial with the base level heading of =. If you want it to reside at a different level on the page in which it is included, offset it accordingly such as in the example shown here.

Both + positive and - negative offsets are okay. You can also use tags for including only certain parts of your partial.

Output

Test include

Hi there. Thanks for including me.


Tables

Tables are a great way to display information. There are a variety of options in asciidoc when using tables.

See asciioc tables for more in-depth information.

Source

[cols="3,7a"] (1)
|=== (2)
|Parameter|Description (3)

|`parameter`
| A nice wee description

|=== (4)
1 Set the columns. In this case 3 and 7 are percentages of 30% and 70%. The a allows for additional information in the column.
2 Set the start of the table.
3 The header row. If you do not want a header, put a space between the |=== and your row.
4 End the table.


Output

Parameter Description

parameter

A nice wee description


Quote blocks

Quote blocks contain, well, quotes. However, they can also be used to highlight important information. But, mostly, for quotes.

See Asciidoctor’s block quote syntax for more details.

Source

[quote,Ilgun]
____
We know how to party, what can I say?
____

Output

We know how to party, what can I say?

— Ilgun


Sidebar block

Sidebar blocks can be used to discuss important items within the context of external information.

We tend to use them for related topics.
.Related topics
****
* xref:contribute/index.adoc[]
****

Code

Write code samples either inline or via a block (where it can be copied).

There are a good few options for including code from external files within code blocks. If you’re interested, check out more on code blocks with asciidoc on its dedicated page.

Source

Inline
Pass the `-G` flag to install the feature globally.
Source code block
[source,java]
----
class Meta{
    public static void main(String args[]){
     System.out.println("How friggin meta is this?");
    }
}
----

Output

Inline

Pass the -G flag to install the feature globally.

Block
class Meta{
    public static void main(String args[]){
     System.out.println("How friggin meta is this?");
    }
}

Tags

Tags let you wrap certain bits of content within an asciidoc page. Typically, you want to keep the usage of tags in partials.

We wrap our Known issues in tags so they can be reused within individual modules.
See asciidoctor tags for more in-depth information.

Source

Open the tag with tag::<name>[]

// tag::known-issue[]

Place the content between the opening and closing tag

This issue is no big deal. It will be fixed shortly.

Close the tag with end::<name>[]

// end::known-issue[]

tags

This issue is no big deal. It will be fixed shortly.

To call a tag via a partial, include::partial$partial-name.adoc[tags="<name>"].


Variables

Variables, or attributes, are exactly that. They are bits of information stored under an alias.

Variables return information verbatim with no formatting.

If you want formatting, you need to format the variable when it is called and not the content as it is stored.

Source

:contribute-variable: How much wood would a woodchuck chuck if a woodchuck could chuck wood?

{contribute-variable}

*With formatting*

`{contribute-variable}`

Output

How much wood would a woodchuck chuck if a woodchuck could chuck wood?

With formatting

How much wood would a woodchuck chuck if a woodchuck could chuck wood?


Conditions

Conditions allow you to use single-source content in places where not all of the information is applicable.

We recommend that only highly advanced users use conditional statements.

Source

:true-love: true

ifeval::["{true-love}" == "true"]
I love you.
endif::[]

:true-love: false

ifeval::["{true-love}" == "false"]
Let's just be friends.
endif::[]

Output

We set the evaluation statement to true.

I love you.

We set the evaluation statement to false.

Let’s just be friends.

You see what we did there?

Code callouts

Code callouts help you reference specific points of information in a code block.

When someone copies your code sample, only the code itself is copied. No need to worry about callouts coming along to mess that up.

Source

Source code block
[source,java]
----
class Meta{
    public static void main(String args[]){
     System.out.println("How friggin meta is this?"); (1)
    }
}
----
<1> I am a super fancy callout.

Output

class Meta{
    public static void main(String args[]){
     System.out.println("How friggin meta is this?"); (1)
    }
}
1 I am a super fancy callout.

Custom asciidoc

Javadoc extension

Source

javadoc:info.magnolia.usagemetrics.ConfigScannerCommand[]

Icons

Use icons to add a bit of personality to the docs or to signal important or exciting items.

See FontAwesome For a list of all available icons.
Pass <N>x such as 2x to increase the icon size. There are limits to the size increase. See FontAwesome for more on this.

Source

icon:rocket[2x]

Output


Tabs

Tabs are useful for toggling between information such as code blocks or multiple options.

Tabs require an extension.

Source

[tabs] (1)
==== (2)
version1-file:: (3)
+ (4)
-- (5)
.v1
[source,yaml]
----
configuration: was this way
----
-- (6)
version2-file::
+
--
.v2
[source,yaml]
----
configuration: is now this way
----
--
==== (7)
1 Call tabs.
2 Open the tab container with ====.
3 Set a tab with ::.
4 Add the +.
5 Set the tab boundary with --.
6 End a tab with --.
7 Close the tab container with ====.

Output

  • version1-file

  • version2-file

v1
configuration: was this way
v2
configuration: is now this way


Custom admonition blocks

There are Standard admonition blocks that come out-of-the-box with asciidoc. However, we have two custom options for:

Best practice

Source
[NOTE.best]
====
You should really do it this way.
====
Output

You should really do it this way.

Alternative important information

Source
[NOTE.alt,caption="Yo! Pay attention to this cool announcement!"]
====
You should really do it this way.
====
Output

You should really do it this way.

Feedback