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:
- Improved content composition.
- Return of the Lisk Protocol documentation.
- Why Lisk chose AsciiDoc over Markdown.
- Simplifying the contributions process.
1. 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:
The complete configuration reference is also listed here.
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.
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 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.
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
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.
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.