Page Comparison

...

• 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: Collaborate 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.

...

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.

Deploy process

Github Pages Specific Issues

Community Workflow

Documentation Parallels Development

Community Process

...

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