Documentation

Workarea documentation is managed and versioned with the platform source code.

Published Documentation

Documentation is published automatically each time a new version of the platform is released. Beginning with Workarea 3.3, each major and minor version of the platform has its own documentation.

Documentation Build System

A documentation build system builds the published documentation from the documentation sources that are included within each distribution of the platform.

The build system is based on the Middleman static site generator. The build system and documentation sources are located at /docs within the Workarea source.

The build system includes Middleman-NavTree for constructing navigation. The YAML file at the path docs/data/articles.yml declares a tree representing the relationships of the platform article documents.

The build system includes Middleman::Search to provide search functionality.

This features requires each document to specify frontmatter for use in the search index. See Document Source Files below.

Documentation Sources

Within Workarea's /doc directory, documentation source files and files that make up the build system are organized according to the Middleman directory structure.

Image Source Files

Image source files are PNG or JPG files whose pathnames match the following pattern:

docs/source/images/*.{png,jpg}

Words within filenames are separated with paths since the filenames are used in published URLs.

Document Source Files

The pathnames of document source files match the following pattern:

docs/source/{articles,release-notes}/*.html.md

Words within filenames are separated with paths since the filenames are used in published URLs.

The format of these documents is proprietary to the build system.

Each file begins with YAML frontmatter, which declares a title and excerpt used for search functionality. Adding a created_at entry to the frontmatter will allow the article to display within the Recent Articles section of the main documentation navigation. This date should be in YYYY/MM/DD format.

Following the frontmatter is Redcarpet markdown with the :tables, :no_intra_emphasis, and :fenced_code_blocks extensions enabled.

Now on GitHub