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[]
slide haidagwaii

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.

Twitter LinkedIn Github Gitlab Meetup RSS Miro Trello Zotero Hypothesis