Transform your markdown documentation into a single navigable html document.
This tool takes a single markdown input file, named README.md by convention, and turns it into a single html page. The target audience are people writing reference documentation for products, APIs or libraries. It was written as a reaction to complex tools and inspired by single page docs like express.
Notable features:
Give it a shot and let me know what you think.
Get started by downloading the code and dependencies. This step you will only need to run once.
git clone https://github.com/philips/fixiedocs.git
cd fixiedocs
npm installNow the fun part: getting a preview of the document. In the same terminal run the following command to launch a server and open your browser.
grunt serverThis browser preview will continue to update everytime you save a change to the README.md file. Lets try that out. Open the README.md file in your favorite editor and start editing. If you aren't familiar with markdown you can find a full guide here. But, you should be able to infer the basics from reading the Fixie Docs README.md file.
In most every case documentation is meant to be uploaded for anyone to read on the public internet. So, lets setup a nice automated process for generating your website on a public URL.
Let's use GitHub's free static HTML hosting called Pages. We will generate the Pages when we commit a change to this git repo using Travis CI. It will be nice and automated.
yo travis-ci:gh-pagesBy default you should have a beautiful set of docs. However, you can
customize the CSS, JavaScript and HTML too. All of it can be found in
the app/ directory.
For example the HTML template will need to be customized if you wish to
add a title or analytics. The template file is called
app/template.jst.
To generate an uploadable static version of the docs locally run the grunt
command in your terminal. This will output all of the necessary HTML, CSS and
JavaScript to the dist/ directory.
There are a ton of other great options for publishing the static documentation that is generated from Fixie Docs. Here are a few suggestions:
There are a lot of features I would love to see. Here are some of them.