Grunt plugin to generate table-of-contents based documentation sites (ala Backbone/Underscore) from a Markdown file.
Grunt plugin to generate table-of-contents based documentation sites (ala Backbone/Underscore) from Markdown.
This plugin requires Grunt
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-tocdoc --save-dev
In your project's Gruntfile, add a section named
tocdoc to the data object passed into
The location in the filesystem (relative to your Gruntfile) where the required CSS file will be written.
The url where the HTML page should look for its required CSS. This may need to be different than the
cssFilePath if you are not writing them both to the root of your project.
In this example, the default options are used to generate API documention from a set of markdown files. So if the
api.md files are valid Markdown, then
index.html will list the overview content first, the api content second, and display a scrollable table of contents on the left-hand side. It will also output a file called
tocdoc.css side-by-side with your
Gruntfile to provide the necessary styles for your doc site.
In this example, custom options are used to specify a different location for the css file because the generated documentation resides in a subdirectory. Note that
cssUrl are not the same in this case. The file path is relative to the
Gruntfile while the
cssUrl is relative to the html page.
Because grunt-tocdoc is based on Bootstrap, you have access to a wide range of CSS components you can use as needed. For instance, if you want to create a download button you can do so like this.
And it will look like this:
(Example is only visible on the tocdoc version of the readme.)
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.