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.
Navigation
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.
Search
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.
Help Us Improve this Doc
Was this helpful? Open a GitHub issue to report a problem with this doc, suggest an improvement, or otherwise provide feedback. Thanks!