https://github.com/h2non/grunt-beautiful-docs
Generate beautiful markdown-based documentation using Grunt
https://github.com/h2non/grunt-beautiful-docs
Last synced: about 2 months ago
JSON representation
Generate beautiful markdown-based documentation using Grunt
- Host: GitHub
- URL: https://github.com/h2non/grunt-beautiful-docs
- Owner: h2non
- License: mit
- Created: 2013-11-25T21:49:25.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2016-02-20T16:56:09.000Z (over 9 years ago)
- Last Synced: 2024-10-18T11:25:24.237Z (8 months ago)
- Language: CoffeeScript
- Homepage: http://beautifuldocs.com
- Size: 214 KB
- Stars: 9
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# grunt-beautiful-docs [][travis] [][dependencies] [][badge]
Generate beautiful markdown-based documentation using Grunt
## Getting started
This plugin helps you to generate beautiful documentation based on markdown files using [Beautiful docs][1] from Grunt
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-beautiful-docs --save-dev
```
Once the plugin has been installed, it may be enabled inside your Gruntfile:
```js
grunt.loadNpmTasks('grunt-beautiful-docs');
```
This plugin requires Grunt `~0.4.0`
## The "bfdocs" task
_Run this task with the `grunt bfdocs` command._
Task targets, files and options may be specified according to the grunt [Configuring tasks](http://gruntjs.com/configuring-tasks) guide
### Usage example
##### Gruntfile configuration
```js
grunt.initConfig({
bfdocs: {
documentation: {
options: {
title: 'My Beautiful Documentation',
manifest: 'manifest.json',
dest: 'documentation/',
theme: 'default'
}
}
}
})
```
Example manifest.json:
```json
{
"title": "My Beautiful Documentation",
"files": [
"README.md",
"GUIDE.md",
"CHANGELOG.md"
]
}
```
_See [Gruntfile][gruntfile] and [test][test] for more configuration examples_
### Options
#### dest
Type: `string`
Default: null
Path to the documentation output directory.
Usually you should use the Grunt file config object to define the destination output directory,
but if you declare this option, it will have preference
#### manifest
Type: `string`|`object`|`array`
Default: null
It can be an `object` like the manifest config or a string with the path to manifest.json file
For more information about manifest.json config options, see the Beautiful Docs [documentation][2]
#### server
Type: `boolean`
Default: false
Create an HTTP server to access the generated documentation
#### port
Type: `number`
Default: '8080'
The port on which the HTTP server shoud listen. It will be used only if the `server` option is `true`
#### watch
Type: `boolean`
Default: false
Watch files for modifications and reload them automatically
#### theme
Type: `string`
Default: 'default'
Name of bundled theme or path to custom theme
#### title
Type: `string`
Default: 'Beautiful docs'
Title of the index page. It can be also defined from the manifest.json file
#### baseUrl
Type: `string`
Default: ''
Base url of all links
#### indexOnly
Type: `boolean`
Default: false
Only generate the index file. The last argument should be the filename of the index
#### manifestsOnly
Type: `boolean`
Default: false
Do not treat the last argument as the output dir but also as a manifest
#### bfdocsBinary
Type: `string`
Default: `node_modules/beautiful-docs/bin/bfdocs`
Use a custom `beautiful-docs` binary path
## Contributing
Instead of a formal styleguide, take care to maintain the existing coding style.
Add unit tests for any new or changed functionality
### Development
Clone the repository
```shell
$ git clone https://github.com/h2non/grunt-beautiful-docs.git && cd grunt-beautiful-docs
```
Install dependencies
```shell
$ npm install
```
Run tests
```shell
$ npm test
```
## Release History
- **0.1.0** `2013-12-12`
- Initial release
## To Do
Do you miss something? Open an issue or make a PR!
## Authors
* [Tomas Aparicio](http://github.com/h2non)
## License
Copyright (c) 2013 Tomas Aparicio
Released under MIT license
[1]: http://beautifuldocs.com/
[2]: https://github.com/maximebf/beautiful-docs#manifests
[gruntfile]: https://github.com/h2non/grunt-beautiful-docs/blob/master/Gruntfile.coffee
[test]: https://github.com/h2non/grunt-beautiful-docs/tree/master/test
[travis]: https://travis-ci.org/h2non/grunt-beautiful-docs
[badge]: http://badge.fury.io/js/grunt-beautiful-docs
[dependencies]: https://gemnasium.com/h2non/grunt-beautiful-docs