Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Icinga Documentation

This repository includes scripts to build the documentation for all Icinga projects.

The build-docs.rb script clones the configured project to a certain directory and switches to the specified branch. It searches for *.md files within the configured directory and creates documentation sections out of them. The ordering is defined by the file names. The capitalized name of each file is used as a title for this documentation section. The generates the mkdocs.yml file.


Usage: build-docs.rb -c config.yml -t mkdocs.template.yml}
    -f, --config FILENAME            Configuration file with project definition. Defaults to "config.yml"
    -t, --template FILENAME          This file is used as template for the generated mkdocs.yaml. Defaults to "mkdocs.template.yml"
    -h, --help                       Show this message



This file defines generally for which project documentation should be build.

General settings:

Option Description
site_name The site_name is displayed as title on the generated page
source_dir' Target directory to store the documentation source.
site_dir Target directory for generated html
project General project settings

Project settings:

Option Description
git Git repository to clone
ref Git branch or tag to checkout. For tags use tags/v1.1.0 notation
target A unique name to define the target. This is added to source_dir and site_dir
docs_dir Directory within the repository that includes documentation files. Eg. doc
latest If set to true, this documentation will be marked as the latest. This is important for the URLs.
subcategories A project may include one ore more sub categories. One sub category may have one or more sub projects

Subcategories are optional. They allow you to display a project documentation within another project documentation. We need this for Icinga Web 2 and Director.


site_name: 'Icinga 2'
source_dir: 'www/source'
site_dir: 'www/html'
  git: ''
  ref: 'support/2.7'
  target: 'icinga2'
  docs_dir: 'doc'
  latest: true

Example with subcategories:

site_name: 'Director'
source_dir: 'www/source'
site_dir: 'www/html'
  git: ''
  ref: 'support/1.4'
  target: 'director'
  docs_dir: 'doc'
  latest: true
        git: ''
        ref: 'master'
        target: 'puppetdb'
        docs_dir: 'puppetdb/doc'


This file is used as a template for the final mkdocs.yml. Default settings and some other configuration options are here.

Run Development Server

To see a live preview of the documentation you can run a development server that will refresh automatically on changes.

Install mkdocs and the material theme in version 1.12.2:

user@localhost ~/ $ pip install mkdocs==0.16.3
user@localhost ~/ $ pip install mkdocs-material==1.12.2

Clone this repository and install dependencies:

user@localhost ~/ $ git clone
user@localhost ~/ $ cd icinga-docs-tools
user@localhost ~/ $ bundle install --path vendor

Create and configure configuration file:

user@localhost ~/ $ cp config.example.yml config.yml
user@localhost ~/ $ vim config.yml

Build documentation:

user@localhost ~/ $ bundle exec build-docs.rb

Run server:

user@localhost ~/ $ mkdocs serve

You should be able to access the documentation now in your browser by calling the address https://localhost:8000


Build environment for




No releases published


No packages published
You can’t perform that action at this time.