Config

Config

The main configuration file for the toolchain is placed in the content root and named config.yaml. This file allows to change all the variables that influence the creation of the documentation, such as multipage level, blacklist files, exclude lists for the search index, etc.

Overview

This sections provides an overview over the different settings in config.yaml.

Asciidoctor

• asciidoc.index.file is the name of the index file which will be converted.
• asciidoc.multipage_level specifies which level the multipage converter will use to split index.adoc into several files.

Build

• build.dir is the build directory for the toolchain.
• build.html.dir is the output directory for the converted HTML documents and assets.

Custom

custom.dir is the directory holding custom extensions and processes. The folder structure must be:

{custom.dir}
- extensions.d
-- extension.rb
- pre.d
-- process.rb
- post.d
-- process.rb

Extensions and Processes

Both extensions and processes can be enabled/disabled selectively. To enable an extension, add the name of the extension (the class name without modules) to extensions.enable. To enable a process, add the name of the process (the class name without modules) to process.pre.enable or process.post.enable.

Naming

The name of extensions and processes is defined by the implementation. A PostProcess might look like this:

module Toolchain
  module Post
    class TestProcess < BaseProcess
    end
  end
end

The name for this particular process would be TestProcess, i.e. the class name Toolchain::Post::TestProcess without the modules Toolchain::Post::.

Checkers

Pattern Checker

The PatternBlacklist reads the blacklist file from the config (checkers.pattern.blacklist; default blacklist.txt) containing a list of words and patterns that are invalid (i.e. must not be used in the documentation).

Search

The search options set both index file and the database file (i.e. lookup file). These settings should not be changed unless you know what you are doing.

The option search.exclude is a list of excluded files. These files will not be indexed and therefore are not visible in the frontend search.

Example Config

# Asciidoctor settings
asciidoc:
  # Specify the index file
  index:
    file: index.adoc
  # Specify the level on which pages will be split up
  # by the multipage converter
  multipage_level: 2

# Build directories
build:
  # Build dir for asciidoctor content
  dir: /tmp/build
  html:
    # HTML dir: output of the asciidoctor build
    dir: /tmp/build/html

# Custom directory for content defined
# extensions and processes
custom:
  dir: custom

# Enable extensions
# List of extension class names which will be loaded
extensions:
  enable:
    - IfChecker
    - IdChecker
    - LinkChecker
    - PatternBlacklist

# Enable processes
# List of process class names which will be loaded
processes:
  pre:
    enable:
      - CombineAndTranspileJS
  post:
    enable:
      - CompileSearchIndex
      - Rename
      - HTMLTest
      - CodeRayStyleCopy

# Settings for individual checkers/extensions
checkers:
  pattern:
    # Specify the blacklist file for the PatternChecker extension
    blacklist: blacklist.txt

# Search index settings
search:
  # DO NOT CHANGE
  index:
    file: lunrindex.json
  # DO NOT CHANGE
  db:
    file: lunrdb.json
  # Exclude the following file from the search index
  exclude:
    - docinfo*.html
    - index.html
    - Imprint.html
    - ContactUs.html

# DEPRECATED
log:
  file: /tmp/log.json

# Table of contents settings
# DO NOT CHANGE
toc:
  json_file: toc.json
  html_file: toc.html