HadiEsna / lisk-docs

📘 Lisk documentation repository

Repository structure and workflow

Lisk uses Antora as a documentation generator.

Table of Contents

• Structure
  • The docs/ folder
  • The ui/ folder
  • The build/ folder
• Product-specific docs
  • Content sources
  • Previous versions

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 improve the UX and follow the 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 following:

• …​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

Note	These branches store either the latest or the 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.