The Lisk Documentation migrated to AsciiDoc and Antora
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.
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.
Improved Content Composition
The current documentation consists of 2 different components:
- Lisk SDK documentation: Technical references, guides, tutorials, and explanations for the Lisk SDK.
- Lisk Core documentation: Technical references, guides, and explanations for Lisk Core.
This is set up in accordance with the grouping categories designed by Daniel Procidas.
The 4 Realms of Documentation
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 pictureand 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 pictureand explain general concepts behind the implementation. |
| References This section comprises the technicalreferences for Lisk Elements, Lisk Commander andthe 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.
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.
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.
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:
New custom UI
To provide the presentation for Antora, a custom UI based on the Antora Default UI has been created.
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.
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:
- How to create feature requests / How to provide feedback
- How to submit a patch
- How to take an open issue / How to submit larger content contributions
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.