The Lisk Documentation migrated to AsciiDoc and Antora

  • By Mona Bärenfänger in Announcement
  • 24 Feb 2020
  • 7 min read

Along with the new website design for lisk.io, the entire documentation workflow has been updated. Together with a variety of many improvements, all existing documentation has now been converted from Markdown to AsciiDoc, powered by Antora. This blogpost covers why the change was implemented, and highlights the most important new features that exist after the migration.

Table of contents:

  1. Improved content composition.
  2. Return of the Lisk Protocol documentation.
  3. Why Lisk chose AsciiDoc over Markdown.
  4. Simplifying the contributions process.

 

1. Improved content composition

The current documentation consists of 2 different components:

This is set up in accordance with the grouping categories designed by Daniel Procidas

The 4 Realms of Documentation

Lisk Documentation migration diagram
Lisk Documentation migration diagram

In the Lisk documentation, these 4 categories are applied as shown in the table below:

Lisk SDK

Lisk Core

Tutorials

All tutorial content is covered here. Within the Tutorial overview, a brief synopsis of all the existing tutorials exists, including the estimated time required to finish each specific tutorial, the level of difficulty, and the key learning points.

Tutorials

No tutorials

Guides

How-to Guides describe in short, how to solve a specific problem.

Guides

In the Lisk Core docs, the Setup, Update and Management sections are all belonging to the Guides realm.

Explanations

Explanations can be found throughout the documentation where applicable, and specifically on the overview and getting started pages. They paint the bigger picture and explain the general concepts behind the implementation.

Explanations

Explanations can be found throughout the documentation where applicable, and specifically on the overview and getting started pages. They paint the bigger picture and explain general concepts behind the implementation.

References

This section comprises the technical references for Lisk Elements, Lisk Commander and the Lisk Framework.

The complete configuration reference is also listed here. 

References

A reference of the Lisk Core API is generated dynamically out of the swagger spec files of public Lisk nodes.

The API spec is presented with Swagger-UI and allows the user to make live API requests to the Betanet, Testnet and Mainnet nodes with public API endpoints.

The complete configuration reference is also listed here. 

 

New internal search

It is now possible to search the entire documentation content via the internal page search powered by Algolia.

Lisk Documentation migration screenshot
Internal Documentation Search

 

2. Coming back soon: Lisk Protocol documentation

At present, the protocol documentation is being updated to reflect the changes coming with the implementation of the new LIPs.

Shortly a new version will be published on docs.lisk.io that will comprise a high-level overview regarding the updated Lisk protocol. In addition, the Lisk Research team is working on much more extensive protocol documentation, which will also be published in the fullness of time.

 

3. Goodbye Markdown, Hello AsciiDoc!

One of the most fundamental and beneficial changes here is the conversion of the documentation files from Markdown to AsciiDoc.

Markdown is a well-known language, whereas AsciiDocs may be considered as relatively new to many users.

However, whilst both of them are lightweight markup languages, and therefore share a lot of similarities, there are various advantages of AsciiDoc over Markdown when writing extensive technical documentation.

Why Lisk chooses AsciiDoc

One standard, no flavors

In contrast to Markdown, AsciiDoc has no specific flavors and follows one uniform specification. This allows the true portability of AsciiDoc documents between different platforms.

At the beginning of 2019, AsciiDoctor started the process of an official AsciiDoc specification to prevent different flavors of AsciiDoc being developed.

Lastly, to extend the abilities of AsciiDoc further, it is possible to use AsciiDoc extensions.

AsciiDoc support is growing

As AsciiDoc is currently less popular than Markdown, hence one of the disadvantages is that there are not many popular tools at present that offer support.

AsciiDoctor, the newest and most popular implementation of AsciiDoc, is already supported by Github, so it is actually possible to write the README files in AsciiDoc as well.

In addition, some of the most popular editors provide plugins for AsciiDoc support such as Visual Studio Code and WebStorm. These plugins allow users to work conveniently and also have a live rendered preview.

Page attributes

Page attributes are an extremely powerful feature of AsciiDoc, as they allow the author to add various additional information to a document. Attributes are always defined at the top of the document, directly below the document title.

Lisk Documentation migration - code snippet
Example: how to use attributes in the documentation

Optimized syntax for technical writing

One simple example of a very convenient built-in attribute is the :toc: attribute. The :toc: attribute adds an auto-generated table of contents to each document. Other syntax examples that are actively used in the Lisk documentation consist of  Code callouts, Videos, Admonitions and conditional preprocessor directives.

In short, AsciiDoc offers the possibility to perform to everything that Markdown (and all its flavors), has to offer, and much more.

For a comprehensive overview of the options, please see the AsciiDoctor User Manual. Useful syntax examples and tips are provided there additionally.

Powered by Antora

Antora is the most modern AsciiDoc based documentation site generator.

Antora turns a collection of AsciiDoc documents into a static website. It can be installed easily with NPM and be used directly from the command line. 

Antora works seamlessly together with AsciiDoc as some of the core developers of AsciiDoctor are actively maintaining the project. Occasionally Antora offers new features that will become part of AsciiDoc in the next release. 

To view more examples of how other projects manage their documentation with Antora, please see the list of projects using Antora.

Follows Docs-as-Code approach

The workflow of Antora makes it easy to follow the Docs as Code approach. Documentation as Code, (or Docs as Code) refers to a philosophy that documentation should be written with the same tools as code:

  • Issue Trackers, (GitHub, GitLab).
  • Version Control, (Git).
  • Plain Text Markup, (Markdown, reStructuredText, AsciiDoc).
  • Code Reviews, (GitHub, GitLab).

A docs-as-code approach simplifies the overall maintenance of the documentation, and lowers the barrier for developers to contribute to it significantly.

Versioning for multiple products

Antora handles versioning of multiple products in a very straightforward manner that makes it unique among documentation generators, even compared to documentation generators that support other lightweight markup languages such as Markdown or reStructuredText.

The versioning of multiple products is extremely important, as this assists with maintaining documentation for many different products with separate versioning schemes.

Versions and components are stored in branches

Antora uses branches to store content for different versions and each branch contains an antora.yml file to categorize to which documentation component this version branch belongs to, and how the version should be labeled.

To understand how the versioning of the content is realized in Antora, please view the current playbook file which can be found in the build branch of the lisk-docs repository.

Storing versions in branches is an excellent approach as branches are relatively inexpensive and easy to maintain.

To change between different versions in the same component, use the version selection on the upper right.

To change between different versions and components, use the component selector at the bottom-left:

Lisk Documentation Migration

New custom UI

To provide the presentation for Antora, a custom UI based on the Antora Default UI has been created.

 

4. Simplified flow for contributions

It is now more straightforward to contribute feedback and own content within the documentation.

'Edit this Page' link to GitHub

Another new feature now implemented on the docs page is a link in the upper right corner, which leads directly to the file on Github which provides the content for that particular page.

Lisk Documentation migration

On GitHub, it is possible to fork the lisk-docs repository, commit your changes on a patch branch, and open a PR to merge the patch branch back into the original branch on lisk-docs.

More details about this can be found below in the new Contribution Guidelines.

New Contributions Guidelines on Github

The  Contributions Guidelines have now been updated to reflect the new workflow of how to contribute to the documentation.

It comprises different levels of contributions, from simple bug reports and patch releases, to 

tackling existing issues in the repository.

Larger contributions such as entire sections or tutorials are also welcome.

For further information on the topics listed below, please see the Contribution Guidelines on Github:

View the new changes 

All the features presented here can now be explored by viewing  lisk.io/documentation.

The implementation of AsciiDoc is a significant step forward with regard to the ever-evolving documentation, and all of these new changes are designed to assist and further help the user. All feedback is very welcome and can be provided via the Lisk Discord server in the #developers channel, or alternatively, an issue can be opened directly in the lisk-docs repository on GitHub.

Technical Writer

Mona graduated in media computer science and works for Lisk as a developer and technical writer. Mona has amazing abilities to write clear and concise documentation. If you can't find her improving the docs, you can find her catching crypto bears!