This tool requires a working version of Pandoc. Once pandoc is working you can use this project to help make nice looking scalable html documentation quickly and easily .
This project uses a simple pandoc template that uses the Adapt.js - Adaptive CSS system and moves the Table of Contents to a sidebar on the left. It also uses the master.css from the project so the generated documentation is consistent between browsers. In short the adaptive css and js scripts adjusts the layout depending on the viewing size of the browser window and will adjust the layout upon resize. It's based on a grid system by the same author who created the 960 Grid System. I moved the associated files around to half a dozen projects at home and work, so decided others might find the bundle useful as well. To this end the project was started. I will continue to enhance the template and add extra features over time as it's usage goes up.
I often find myself looking things up on my tiny smart phone and wishing the page layout was scaled better. To this end I started playing with several approaches that allow pages to be displayed well on various sized display windows. The technology that makes this easiest for me and that adjusts to my phone orientation is Adapt.js - Adaptive CSS. Since I often will refer to my own documentation on my cell I wanted my documentation to have this feature. So by combining Adapt.js - Adaptive CSS with the Pandoc Templating System I am able to create documentation that displays nicely on on a variety of resolutions.
Pandoc is my choice for creating documentation. Pandoc makes it easy to output documentation is several different formats and uses an enhanced markdown syntax to accommodate more advanced features such as tables, footnotes and strikeout as well as others. In addition it is cross platform and has installers for Windows and OSX. If you use Linux many distributions have packages or you can build from source available at the previous URL. A common alternative I also use for python projects is Sphinx - Python Documentation Generator.
The Adapt.js and this project are both dual licensed under GPL and MIT. No strings attached.
This document is included as documentation.markdwon so you can use it as an example and to test generation. The following information should be helpful when you first get started.
- The build script expect the documentation files to end in .markdown
- It's easier to organize if you use a separate file per section/chapter when authoring and let pandoc combine.
- Use the Pandoc User Guide for additional formatting information.
Once you have a copy of the Pandoc-Quick-Start-With-HTML-Template you should be able to start writing documentation. By default the supplied build scripts will combine the files in your working directory in the order generated by the file listing command given in each, generally alphabetically. You can also specify the files on the command line. Either way the output file is aways index.html. Both scripts are trivial and if I have many sections of documentation I rename the files to achieve the desired order or copy the build script into the directory under a new name, then customize and use.
# Ordered by OS listing
./build.sh
# Order Supplied on Command Line
./build titlepage.markdown chapter1.markdown chapter2.markdown
To make it easier to update the template and other files I suggest using symbolic links back to where your documentation source is.
# To make linking easier you can set an environment variable
export DOC_HOME=[Path to Where You have Pandoc Quick Start With HTML Template]
# Make a docs directory
mkdir docs
cd docs
# These are the documentation files needed to successfully generate templates
ln -s $DOC_HOME/css $DOC_HOME/js $DOC_HOME/html.template $DOC_HOME/build.sh `pwd`/.