Infusion Documentation Architecture and Process

Work in Progress

This document is work in progress.

The documentation for Fluid Infusion transitioned from being hosted on a Wiki style content management system (or CMS) to a system of statically generated and statically hosted content.

Choosing to Go with a Static Site

A "static site" generally refers to a website where the content is generated in advance and served to clients. This approach was the de-facto method of creating and serving web content in the early days of web development where HTML was written by hand and site navigation manually maintained by the administrator. The major problem with maintaining these early static sites was that they were very cumbersome to maintain and update - this helped fuel the rise of CMS based websites (like Wordpress, Drupal, and a host of other platforms).

A CMS website generally has two main components: a database which stored the content, and front-end which was responsible for rendering the content which the user sees. For a while, the Fluid Project used a CMS to maintain its documentation for Fluid Infusion, but eventually migrated to using a static approach with the help of a static site generator.

There were a few reasons for deciding to go with a static site:

Ease of adding and editing content: each piece of content is an actual text file which can be edited using a standard text editor.
Enables collaboration: since content are files, these files can be maintained using a distributed work environment like Github. Multiple editors can work on content simultaneously and all changes are versioned and tracked.
Use existing community process: Fluid already has an established community process for its development. The same community process of forking, branching, and issuing pull requests can be used for the Infusion documentation. See: Get Involved and Contributing Code for more information on the Fluid development process.
Ease of releases: documentation can be tagged for different versions making packaging easier.
Security concerns are mitigated primarily because there isn't a database to maintain.
Extensible: the content is flexible and not bound to any particular platform thus allowing the content to be re-purposed.
Automation: using github as the repository for the content, it is possible to automate generation and deployment.

Moving to Static Site and Creating Content

A static site generator is software which eases the development and deployment of static sites. Fluid has previously researched static site generators (see: Static Site Generator Usage Notes) and have decided to use Docpad.

Note: This documentation assumes you have some understanding of how Docpad works (try their tutorial to get started: https://docpad.org/docs/begin). For more information, visit the Docpad website https://docpad.org/.

Content and Templates

In Docpad, content are stored in text files (written in plain text, HTML, Markdown etc.) and laid out according to templates. While Docpad supports various text formats, the Infusion documents were written in Markdown. Markdown was used because it can be viewed natively in Github, and there is a low barrier to learning the syntax thus making it easier for contributors.

Note: In some cases, Markdown lacks additional formatting such as tables and definition lists. In these cases the Markdown files will also have HTML. For example: ChangeApplierAPI.md in github shows a Markdown file mixed with HTML markup.

A template is used to lay out the content contained in the Markdown files. For the Infusion documentation, we chose to use Handlebars the template markup as it helps preserve the validity of the HTML file. The template resembles a typical HTML file complete with HTML tags and CSS classes, but in place of the content there will be Handlebars blocks. These Handlebars blocks are then replaced with the content from the Markdown files when generating the static site.

Example:

Take this Markdown content file from the Infusion documentation - https://raw.githubusercontent.com/fluid-project/infusion-docs/master/src/documents/Contexts.md
and this template file from the Infusion documentation - https://github.com/fluid-project/infusion-docs/blob/master/src/layouts/default.html.handlebars
when processed and rendered by Docpad would output this - http://docs.fluidproject.org/infusion/development/Contexts.html

Structuring Content

The Infusion documentation is structured in the following way:

./                      (Docpad configuration, site navigation, README and license information)
./src/documents/        (Document content written in Markdown)
./src/ghpages-files/    (Files specific to serving a website through Github pages)
./src/layouts/          (Handlebars templates)
./src/static/           (CSS files, fonts, icons / images, etc., 3rd party libraries and Javascript)

./out/                  (Where Docpad creates the generated output)

The project should be self-contained, meaning it can be viewed, edited, and built without any requisite directory structure.

Managing the Table of Contents

There are multiple tables of contents for the Infusion docs - API, Tutorials, and Infusion. Depending on which document is being viewed by the user, one of the relevant table of contents is displayed in the sidebar. This means that we need something that defines the index or structure of the table of contents, as well as a way of defining which table of contents to display when viewing a particular page.

site-structure.json

Navigation for the Infusion documentation is primarily handled by the file ./site-structure.json. This file contains information about how the table of contents should be structured - see the living example on github to understand how it works. With this JSON file, we are able to manually sort Pages into Catgeories and Sections, and define the URLs for each item in the table of contents.

Category metadata

Each content page also has a category YAML metadata in the front matter. For example, the DOM Binder API document belongs in the API category:

---
title: DOM Binder API
layout: default
category: API
---
The DOM Binder provides a degree of separation between a component and its interface by ...

By specifying a category value in the metadata, Docpad will know which category's table of contents to render. Without this value, a table of contents will not be displayed.

Deploying Content

Build process To-do

Checklist

Plugins: marked, handlebars
Markdown content goes into ./src/documents
Site-structure.json defines the table of contents

Relative Paths To-do

For Infusion docs we use relative paths where possible to make it easier to develop and edit.
When generating the output, the handlebars help converts paths to paths relative to the current document.
There is an open issue where the 404 page has hardcoded paths.

Testing and Deploying To-do

To test locally:
- run docpad run --env static
- open browser to http://localhost:9778/

Hosting and deploying to gh-pages To-do

To deploy to your own gh-pages repository
- take the contents from the ./out directory and push it to your gh-pages branch.
- there is a gh-pages plugin for docpad that you can use that push the contents of ./out to a gh-pages branch. See: https://github.com/docpad/docpad-plugin-ghpages
Note: custom 404 error pages for gh-pages will only work for sites hosted from the root domain.

Community Workflow To-do

Documentation parallels development - whenever Infusion changes, there should be an accompanying update to the documentation if required.
updates and additions to the docs follows the same process as development:
- Fork the Master, work in a branch in your repository, submit a pull request.

Future Improvements To-do

Automating deployment