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
-
Task for compiling a new version of the Lisk documentation: deployment.liskdev.net/job/lisk-docs-build/
-
Task for deploying the latest docs on staging.lisk.com: deployment.liskdev.net/job/lisk-docs-deploy-staging/
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
-
Task for compiling a new version of the Lisk documentation: deployment.liskdev.net/job/lisk-docs-build/
-
Task for deploying the latest docs on staging.lisk.com: deployment.liskdev.net/job/lisk-docs-deploy-production/
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
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 -- =====