Style library

Introduction

The styleguide repository contains an Antora component that can be included as a library in a documentation site. This component does not define any pages, but contains files in the other content families: images, snippets, examples, and so on.

The Antora UI for drostan is adapted to not include the library when building the site components menu.

This effectively makes it a hidden component.

Adding the style library to a site

In the playbook, add the library component repository like below:

# ...

content:
  sources:
  - url: .
    branches: main
    start_paths:
    - docs/component1
    - docs/component2

  - url: https://gitlab.com/rolfkleef/drostan-styleguide.git
    branches: main
    start_paths:
    - lib/antora

# ...

Including elements from the library

Use standard Antora references to include elements:

Example 1. Include a partial

include::lib-style::partial$example.adoc[]

I am an example library item taken from the style guide.

Example 2. Include an image

image::lib-style::slide-haidagwaii.png[]

Adding the style library as git submodule

You can also add the styleguide repository as git submodule to the repository containing the Antora playbook.

$ git submodule add https://gitlab.com/rolfkleef/drostan-styleguide.git styleguide

Adding the styleguide as submodule will make other style elements available:

A PlantUML configuration file that can be inserted in each diagram, to create consistent styling.
Vale style libraries to check writing style.
CSL definitions to use in Zotero bibliography exports.

It appears that using a git submodule as start path in the playbook does not work.

Also, using the submodule directory as git source does not work: the directory does not contain a regular git directory.