Contributing to the Docs

The Apache Brooklyn documentation is written in kramdown a superset of Markdown which is processed into HTML using Jekyll. In addition to the standard set of options and notation available with these platforms, a number of custom plug-ins have been implemented specifically for the Apache Brooklyn docs. These are detailed below:

Jekyll plug-ins are written in ruby and kept in the _plugins folder. Note that if you’re using jekyll serve to display the site, changes to these plug-ins will not be reflected in the rendered site until jekyll is restarted.

Site Structure

The site structure and menus are built by a plug-in in site_structure.rb. This plug-in looks in the YAML front matter for child pages to build the structure, and breadcrumbs to determine the parent pages to display.

Child pages are a list of objects, stored in the field children. These are defined by string path to a file or a YAML object with a path to another file, or a link to an external URL. In addition a title can be defined for the text content of the HTML menu option. See the example below from /guide/index.md

breadcrumbs:
- /website/documentation/index.md
- index.md
children:
- { path: /guide/start/index.md }
- { path: /guide/misc/download.md }
- { path: /guide/concepts/index.md }
- { path: /guide/blueprints/index.md }
- { path: /guide/java/index.md }
- { path: /guide/ops/index.md }
- { path: /guide/misc/index.md }

Inline Children

In addition to the children property defining lower pages in the site structure, they can also be used to define inline sections within the current document. Inclusion in this way produces a menu link to an anchor in the current page.

Below is an example from /guide/ops/persistence/index.md:

children:
- { section: Command Line Options }
- { section: File-based Persistence }
- { section: Object Store Persistence }
- { section: Rebinding to State }
- { section: Writing Persistable Code }
- { section: Persisted State Backup }

Inline sections can also be detected from separate, child .md files. Including the tag check_directory_for_children: true in the YAML front matter of a page causes the site structure plug-in to look through the current directory for any .md files containing section_type: inline in the YAML front matter.

The content from these inline sections can then be included in the page content using the liquid tag child_content. This is shown below in an example from /guide/locations/index.md:

---
title: Locations
layout: website-normal
check_directory_for_children: true
---

Locations are the environments to which Brooklyn deploys applications, including:

Brooklyn supports a wide range of locations:

* <a href="#clouds">Clouds</a>, where it will provision machines
* <a href="#localhost">Localhost</a> (e.g. your laptop), 
  where it will deploy via `ssh` to `localhost` for rapid testing
* <a href="#byon">BYON</a>, where you "bring your own nodes",
  specifying already-existing hosts to use
* And many others, including object stores and online services

Configuration can be set in `brooklyn.cfg`
or directly in YAML when specifying a location.
On some entities, config keys determining matching selection and provisioning behavior
can also be set in `provisioning.properties`.

{% child_content %}

Child Page Ordering

Child pages are by default, ordered by their position in the children YAML front matter field. This can be changed using the property section_position in the child YAML. For children defined in the front matter this is put in the child object of the children array.

For inline children, sourced using check_directory_for_children: true, this section_position property is put in the child file’s YAML front matter.

The format for section_position is that of software versioning, i.e A.B... Z where A, B etc are numbers of decreasing value. Position 1.1.0 would appear before version 1.0.4 for example. This allows an infinite number of sub pages between each section_position.

Any un-versioned pages are automatically numbered to add a new minor version from the last page if that was numbered or increment the minor if it was not. If no pages are yet numbered, the numbering is started at 1.1. For example, if a numbered page, 1.4 is followed by a non-numbered page, the non-numbered page would be auto-numbered as 1.4.1. If this page is followed by another non-numbered page it would be auto-numbered as 1.4.2.

For example, a set of children pages numbered like this:

children:
- { path: /guide/start/index.md, section_position: 3.1.2 }
- { path: /guide/misc/download.md }
- { path: /guide/concepts/index.md }
- { path: /guide/blueprints/index.md }
- { path: /guide/blueprints/java/index.md }
- { path: /guide/ops/index.md, section_position: 2 }
- { path: /guide/misc/index.md }

Would end up numbered like this:

children:
- { path: /guide/ops/index.md, section_position: 2 }
- { path: /guide/misc/index.md, section_position: 2.1 }
- { path: /guide/start/index.md, section_position: 3.1.2 }
- { path: /guide/misc/download.md, section_position: 3.1.2.1 }
- { path: /guide/concepts/index.md, section_position: 3.1.2.2 }
- { path: /guide/yaml/index.md, section_position: 3.1.2.3 }
- { path: /guide/java/index.md, section_position: 3.1.2.4 }

This ordering affects both the position of the child in the html menu and the order of content included with child_content.