Document Formating
Bigledger Akaun Platform documentation is produced using Asciidoc format and Antora documentation pipeline. The following sections contains resource links that allow you to deep dive into technology. For a Quick Tips to be hand-on without getting into the details, please refer to Quick Tips for Document Formatting
Asciidoc Guide
Asciidoc is the format or syntax of the Asciidoc Document. You may look at it as a content markup language, just like how HTML has been used as the content markup language that forms the internet pages.
Some useful videos:
Antora Guide
Antora is a documentation pipeline that enables docs, product, and engineering teams to create, manage, remix, and publish documentation sites composed in AsciiDoc and sourced from multiple versioned content repositories. Asciidoctor is the Ruby-based text processor for parsing AsciiDoc® into a document model and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, EPUB 3, and other formats.
Quick Tips on Syntax
There are only a few asciidoc syntax that documentor required to be familiar to kick-off document authoring. It is a straigtforward once you are understand them and you would be sailing from here onwards!
1. Section Title and ID
A section title marks the beginning of a section and also acts as the heading for that section. The section title must be prefixed with a section marker, which indicates the section level. A section marker can range from two to six equal signs and must be followed by a space.
An anchor (aka ID) can be defined almost anywhere in the document, including on a section title. It is used an location anchor for cross referencing purpose.
Example:
\[<section-id>\]
<section-marker> <section-title>Tips: ** Please ensure that there is a space between section marker (equals signs) and section title
2. Images
You may place the images anywhere in any sub-folders inside the "images/" folder in each module, and reference to it in your asciidoc document using the image macro.
Example:
image::<image-file-name>[Some image description]Tips: Please ensure that you do not leave any space between <image-file-name> and the square bracket [] To avoid any unexpected results, please ensure naming your image file without space in between. You can put a dash (- or _) in between if you want to separate the words. Please also ensure that <image-file-name> reflect the same image file name.
3. Cross References
You may cross reference any section of the same document, any section of another document in the same module, and also any section of another document in another module.
Example:
xref::<section-id>[Some Section description]
xref::<document-name>#<section-id>[Some section description]
xref::<component-name>:<module-name>:page$<document-name>#<section-id>[Some section description]Tips: For a full understanding of the above resource ID format, refer to https://docs.antora.org/antora/latest/page/resource-id-coordinates/ Please ensure that you do not leave any space between <section-id> and the square bracket
4. Miscellaneous Tips
-
The title of each section and subsections to have short and concise headings.
-
Please have the correct marker (==) for each title of the subsection.
-
You may create bullet list by preceding each line with single or two asterisks. When creating bullet point in the AsciiDoc, please left a blank line before it so that it will not merge together with the paragraph.
-
To mark a word or phrase as bold, you can enclose it in a single pair of asterisks **.
-
Please remember add the added pages in the index.adoc and nav.adoc.
-
If you are adding a new applet, please remember to check and the applet’s index.adoc and nav.adoc in the antora.yml and folder’s index.adoc.
-
Please check the antora.yml and folder’s index.adoc do not contain duplicate applet’s index.adoc.
-
Please remove or comment out irrelevant pages.
-
Please run the File > Save command before you commit and push the content to prevent error when deployment.