https://github.com/joshuacc/grunt-tocdoc
Grunt plugin to generate table-of-contents based documentation sites (ala Backbone/Underscore) from Markdown.
https://github.com/joshuacc/grunt-tocdoc
Last synced: about 1 month ago
JSON representation
Grunt plugin to generate table-of-contents based documentation sites (ala Backbone/Underscore) from Markdown.
- Host: GitHub
- URL: https://github.com/joshuacc/grunt-tocdoc
- Owner: joshuacc
- License: mit
- Created: 2013-11-11T13:42:55.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2020-07-15T20:01:32.000Z (almost 5 years ago)
- Last Synced: 2025-03-25T18:40:28.900Z (about 2 months ago)
- Language: CSS
- Size: 40 KB
- Stars: 2
- Watchers: 2
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE-MIT
Awesome Lists containing this project
README
# grunt-tocdoc
> Grunt plugin to generate table-of-contents based documentation sites (ala Backbone/Underscore) from Markdown.
[See how this README looks as a tocdoc.](http://joshuacc.github.io/grunt-tocdoc/)
[](https://codeclimate.com/github/joshuacc/grunt-tocdoc)
## Getting Started
This plugin requires Grunt `~0.4.1`
If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
```shell
npm install grunt-tocdoc --save-dev
```
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
```js
grunt.loadNpmTasks('grunt-tocdoc');
```
## The "tocdoc" task
### Overview
In your project's Gruntfile, add a section named `tocdoc` to the data object passed into `grunt.initConfig()`.
```js
grunt.initConfig({
tocdoc: {
options: {
// Task-specific options go here.
},
docSite: {
// Target-specific file lists and/or options go here.
},
},
})
```
### Options
#### options.cssFilePath
Type: `String`
Default value: `'tocdoc.css'`
The location in the filesystem (relative to your Gruntfile) where the required CSS file will be written.
#### options.cssUrl
Type: `String`
Default value: `'tocdoc.css'`
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.
#### options.scripts
Type: `Array`
Default value: `null`
An array of paths to JavaScript files to load on the generated HTML page. This allows you to do things like let people experiment with your library by just visiting your site and playing in the browser console.
### Usage Examples
#### Default Options
In this example, the default options are used to generate API documention from a set of markdown files. So if the `overview.md` and `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.
```js
grunt.initConfig({
tocdoc: {
options: {},
docSite: {
files: {
'index.html': ['overview.md', 'api.md'],
}
}
}
})
```
#### Custom Options
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 `cssFilePath` and `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.
```js
grunt.initConfig({
tocdoc: {
options: {
cssFilePath: 'docs/styles.css',
cssUrl: 'styles.css',
scripts: ['js/jquery.js', 'js/my.jquery.plugin.js']
},
docSite: {
files: {
'docs/index.html': ['overview.md', 'api.md'],
}
}
}
})
```
### Using Bootstrap styles
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.
```html
Download AwesomeLibrary.js
```
And it will look like this:
(Example is only visible on the [tocdoc version of the readme](http://joshuacc.github.io/grunt-tocdoc/#using-bootstrap-styles).)
## Contributing
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](http://gruntjs.com/).
## Release History
### 0.1.1
Added `scripts` property to support custom JavaScript on the generated HTML page.
### 0.1.0
Initial release.
[](https://bitdeli.com/free "Bitdeli Badge")