Repository structure and workflow

Lisk uses Antora as a documentation generator.

All files for the Lisk documentation are stored in the GitHub repository at github.com/LiskHQ/lisk-docs.

Environments

GitHub Pages

The testing and WIP environment for the Lisk documentation. Link to the WIP Lisk documentation: liskhq.github.io/lisk-docs.

  • Source content is stored in the development branch.

  • Compiled files are stored in the git-page branch.

Staging

The staging environment mirrors the production version of the website. Link to the production version of the Lisk documentation: staginglisk.com/documentation.

Documentation is deployed on staging before deploying on Production, to verify the latest updates of the documentation.

  • Source content is stored in the main branch.

  • Compiled files are stored in the live branch.

Deployment

For accessing Jenkins, it is necessary to connect to the lightcurve network via the VPN, if you are not in the office.

Production

The official and public location of the Lisk documentation. Link to the production version of the Lisk documentation: lisk.com/documentation.

  • Source content is stored in the main branch.

  • Compiled files are stored in the live branch.

Deployment

For accessing Jenkins, it is necessary to connect to the lightcurve network via the VPN, if you are not in the office.

Structure

The internal structure of development and main branch.

The docs/ folder

The source content for the general Lisk documentation is located in the docs/ folder.

The file structure follows the expected structure for Antora documentation, see: docs.antora.org/antora/latest/standard-directories/.

All content is written in AsciiDoc.

The ui/ folder

The presentation of the documentation is stored completely separate from the actual content.

The UI is based on the Antora default UI (see also docs.antora.org/antora-ui-default/).

It is customized as listed in the following points below:

  • Updated the CSS to follow improve UX and follow Lisk brand styleguide.

  • Added additional features, such as:

    • Algolia site search

    • Dark theme

    • Zoom for images

    • Additional layout for swagger UI

    • Tab-blocks

    • …​

The build/ folder

The build folder contains…​

  • …​the site.yml file, which is used to generate the Lisk documentation using Antora.

  • …​the searchdocs-scraper folder, for creating the search index.

  • …​the lib folder, which stores the Asciidoc extensions, that are used in the Lisk documentation.

.
├── lib/ (1)
├── searchdocs-scraper/ (2)
├── live-site.yml (3)
└── site.yml (4)
1 The lib/ folder contains extensions for Antora. The extensions are specified in the playbook file of Antora.
2 The searchdocs-scraper/ folder contains the file required to update the Algolia search index of the documentation.
3 The playbook used to compile the live documentation on lisk.com/documentation with Antora. Results are pushed to the live branch.
4 The playbook used to compile the documentation at liskhq.github.io/lisk-docs with Antora. Results are pushed to the git-page branch.

Product-specific docs

There are additional content sources, which each store the documentation for a specific software product of Lisk.

Content sources

These branches store the latest or WIP versions of each component.

  • docs-sdk

  • docs-core

  • docs-service

Previous versions

  • docs-COMPONENT-v1

    where

    • COMPONENT can be either sdk, core or service.

    • v1 represents the respective version number of the corresponding product.

Antora & AsciiDoc

Asciidoc extensions

The following Asciidoc extension is currently used:

Tabs

A clone of gitlab.com/antora/antora-asciidoctor-extensions.

How to create 2 tabs in Asciidoc
[tabs]
=====
Tab1 title::
+
--
Tab1 content
--
Tab2 title::
+
--
Tab2 content
--
=====