AsciiDoc styleguide

AsciiDoc & Antora references

The AsciiDoc and Antora documentation can be used as a general reference for creating valid documentation content.

More specific rules and examples of how to create documentation content in AsciiDoc are described in the sections below.

Document header

= On-chain architecture (1)
Mona Bärenfänger <[email protected]> (2)
// Settings (3)
:toc:
:imagesdir: ../../assets/images
// External URLs (4)
:url_github_sdk_5_modules: https://github.com/LiskHQ/lisk-sdk/tree/v5.0.0/framework/src/modules
:url_github_dpos: {url_github_sdk_5_modules}/dpos
:url_github_keys: {url_github_sdk_5_modules}/keys
:url_github_sequence: {url_github_sdk_5_modules}/sequence
:url_github_token: {url_github_sdk_5_modules}/token
// Project URLs (5)
:url_framework_reference: references/lisk-framework/index.adoc
:url_explanations_communication: architecture/communication-architecture.adoc
:url_references_framework_baseasset: {url_framework_reference}#the-baseasset
:url_references_framework_basemodule: {url_framework_reference}#the-basemodule
1 Page title. Always start with a H0 heading (a single =)
2 The author of the page (optional).
3 Add all desired asciidoc attributes for this document below.
4 Add all external URLs used in this document below.
5 Add all internal URLs used in this document below

Always set link attributes to simplify the management of links.

Please read the guide about link attributes in AsciiDoc.

Link attributes are ordered alphabetically.

Naming convention for link attributes:

  • Always start with the prefix url.

  • Use an underscore _ as the separator between words.

  • Describe a link with as few words as possible.

  • Be consistent and use the same names for the same links, and similar names for similar links.

Examples:
:url_github_core: https://github.com/LiskHQ/lisk-core

:url_guides_config_default_values: lisk-sdk/guides/configuration.html#modify_default_values

For more information, see the Navigation Link Syntax, Content, and Styles chapter of the Antora documentation.

Please also refer to the Lisk docs link styleguide.

Internal links are relative links starting from the pages folder of a module.

Source: https://docs.antora.org/antora/2.2/asciidoc/page-to-page-xref/

xref macro anatomy diagram

Examples for setting different link attributes with internal links from various sources:

:url_index: index.adoc
:url_topic_page: topic/page.adoc
:url_module_page: other-module:page.adoc
:url_component_page: v2@other-component::page.adoc
:url_component_module_page: v2@other-component:module:page.adoc

How to add the above defined internal links in the content:

xref:{url_index}[In-module link]
xref:{url_topic_page}[In-module link to a topic folder]
xref:{url_module_page}[Link to another module in the same component]
xref:{url_component_page}[Link to a page in another component in the ROOT module]
xref:{url_component_module_page}[Link to a page in another component in a specific module]

To have the anchor links working already while creating the content, add the following attriubtes to the content page:

:idprefix:
:idseparator: -

Anchor IDs are automatically generated from the section titles of a page.

== Some title
=== Sub title

Resulting anchor IDs: #some-title and #sub-title

How to link to the ID from the same page

Use the Anchor links to refer to a section on the same page.

We'll walk through a <<some-title,detailed example>> in this tutorial.

How to link to the ID from a different page

Set a link attribute.

:url_anotherpage_foobar: another-page.adoc#some-title

Use the link attribute in the content.

xref:{url_anotherpage_foobar}[An in-module page anchor link]

How to create a custom anchor ID

Titles can change and therefore anchor links break easily. Sometimes it can be useful to set a custom anchor ID:

[[foobar]] (1)
== Some title

It is also possible to place an inline anchor point, for example [[foobar2]]here (2)
1 Changes the anchor ID for the section from #some-title to #foobar.
2 Sets an inline anchor ID foobar2, which allows jumping to certain parts in the content inside of a sentence.

Open external links in a new tab by appending ^ to the link title.

How to define an external link attribute:

:url_github_core: https://other-website.com/url

How to place the external link in the content:

{url_github_core}[Link to another website^]

Other page attributes

TOC

Add a table of contents.

:toc:

The table of content is intentionally not visible in the Antora generated docs, as Antora generates a separate toc out of the content. It still makes sense to include it, to render the table of contents on other occasions, such as on GitHub.

Set custom Next and Previous links to the end of a page:

:page-previous: /lisk-sdk/index.html
:page-previous-title: Overview
:page-next-title: Getting Started
:page-next: /lisk-sdk/getting-started.html

Don’t show Next or Previous links at the end of a page.

:page-no-previous: true
:page-no-next: true

HTML meta descriptions

If the page doesn’t provide an adequate introduction sentence, add this attribute to provide web crawlers with an HTML meta description for this page.

:description: The Lisk SDK Setup page describes...

Line breaks

For every new sentence, use a new line. This keeps a better overview while writing. Asciidoctor will still render the text as one paragraph.

To start a new paragraph use 2 new lines.

Use one line for each sentence.
This maintains a better overview while writing.
Asciidoctor will still render the text as one paragraph.

To start a new paragraph use 2 new lines.

Avoid line breaks if possible. However, if it is necessary then add a + at the end of the line.

This is one line, +
And here starts a new line!

Capitalization

  • Use capital letters for product names.

  • Don’t capitalize words in a heading which you wouldn’t capitalize in a normal sentence.

  • ID is always written all uppercase (except in variable names).

  • Transaction types are always written all lowercase (Except in variable names, e.g. RegisterDelegateTransaction), e.g.:

    In DPoS systems, each account that has enough balance to send a delegate registration transaction and hasn’t done so before, can register a new delegate on the network.

Images

Images are saved in the modules/ROOT/assets/images folder.

If you include an image on a page, set the :imagesdir: attribute, to make sure it will be displayed in your editor preview and on GitHub.

The imagesdir path needs to be always relative to the location of the current page.

Example
:imagesdir: ../assets/images

After placing the imagesdir attribute, insert an image by referring to its file name.

image:banner_sdk.png[Logo]

Admonitions

Use Admonitions to highlight important statements for the user.

Single line Admonitions

NOTE: General information to highlight.
TIP: To explain short cuts, best practices, optional tips.
IMPORTANT: Highlight important content, that the user should not miss.
CAUTION: Highlight content, where the user has to be careful.
WARNING: Warn users about bad consequences that can happen.
General information to highlight.
To explain short cuts, best practices, optional tips.
Highlight important content, that the user should not miss.
Highlight content, where the user has to be careful.
Warn users about bad consequences that can happen.

Multi line Admonitions

[NOTE]
====
This is a multi-line admonition.

It can also have other elements included, such as lists:

* one
* two
* three
====

This is a multi-line admonition.

It can also have other elements included, such as lists:

  • one

  • two

  • three

Headings

Use the following heading levels, never skip heading levels on a page and always use only one H0 title. Titles are being written in sentence case, i.e. small letters except for the first letter of the first word, names or abbreviations.

= Title
== Subtitle
=== Sub-subtitle
== 2nd subtitle

Monospace

The font Monospace should be used in the following cases:

  • Variables

  • File names

    Open file `path/to/file.js` and create a new variable `test`.

Code snippets

Use the following syntax for displaying code snippets:

Bash script example
[source,bash]
----
mkdir folder
cd folder
----

This syntax allows specifying the language of the code in the snippet, which will highlight the code accordingly in the UI.

Commonly used languages in the docs are as follows:

  • js: JavaScript

  • jsx: React JSX

  • typescript: TypeScript

  • bash: Bash

  • json : JSON

For code snippets that do not require a syntax highlight, just omit the language option or as an alternative prepend a space in front of each code line.

Titles for code snippets

Give a code snippet a title by adding a link starting with a dot.

.myproject/src/
[source,bash]
----
mkdir folder
cd folder
----

It is good practice to include the current file path of the file which contains the code snippet as a title.