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.

Single Page Manual and PDF

A single page overview of selections of the site are available in zoneMergeManual and zoneMergeStarted. These overviews are for the user manual and getting started guide respectively. The zone merge pages go through the site structure, described above, and compile the files from this into a single HTML page.

In order to do this, each page is iterated over in order and it’s rendered content included in the page. The plug-in regex_filter.rb is used to re-write <a> links from the structured site into a form which works on a single page. Links are re-written in the following manner:

  • If the link is from an external domain, leave it as an unaltered link
  • If the link is an anchor, convert to the anchor scheme used in the single page
  • If the link target is in the single page, change the link to point at the anchor in the single page
  • If the link is pointing at somewhere on the brooklyn site which is not included in this single page, point to the website with a specific version, so https://brooklyn.apache.org/v/0.9.0-SNAPSHOT/start/concept-quickstart.html for instance

In addition, all images src’s are re-written relative to the root directory.

Pages can be masked from the compilation process by defining a page_mask in the YAML front matter of the zone merge file, then including this mask as true in the child page to exclude. These pages will then not be included in the compiled single page. Note that this will mask both the child page and any children of this masked page. For example zoneMergeStarted uses the mask started-pdf-exclude:

title: Apache Brooklyn Manual
layout: singlePage
page_mask: started-pdf-exclude
...

Then in latter pages, such as /guide/ops/index.md include started-pdf-exclude: true to exclude this section from the getting started guide.

title: Operations
started-pdf-exclude: true
...

This will exclude not only the operations page but all of the operations section.

Specific content can be also be masked or unmasked at a page component level by specifying CSS show and hide classes:

css_hide_class: usermanual-pdf-exclude
css_show_class: usermanual-pdf-include

If the above YAML is included in the front matter of a zone merge file, the classes usermanual-pdf-exclude and usermanual-pdf-include will add or remove a display: none to a HTML object. In addition the single page theme files singlePage.html and singlePage.css can be used to style only the single merged pages.

Conversion to PDF

These single merged pages are then converted to PDF using wkhtmltopdf in the build scripts of this site.