Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/prantlf/grunt-mdoc
Grunt plugin generating HTML documentation from Markdown sources using mdoc
https://github.com/prantlf/grunt-mdoc
documentation-generator grunt-plugins mdoc
Last synced: 28 days ago
JSON representation
Grunt plugin generating HTML documentation from Markdown sources using mdoc
- Host: GitHub
- URL: https://github.com/prantlf/grunt-mdoc
- Owner: prantlf
- License: mit
- Created: 2015-01-29T20:40:17.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2019-12-27T12:46:05.000Z (about 5 years ago)
- Last Synced: 2024-12-01T15:12:36.253Z (about 1 month ago)
- Topics: documentation-generator, grunt-plugins, mdoc
- Language: JavaScript
- Size: 195 KB
- Stars: 1
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# grunt-mdoc
[](http://badge.fury.io/js/grunt-mdoc)
[](https://travis-ci.org/prantlf/grunt-mdoc)
[](https://coveralls.io/r/prantlf/grunt-mdoc)
[](https://david-dm.org/prantlf/grunt-mdoc)
[](https://david-dm.org/prantlf/grunt-mdoc#info=devDependencies)
[](https://david-dm.org/prantlf/grunt-mdoc#info=peerDependencies)
[](https://codeclimate.com/github/prantlf/grunt-mdoc)
[](https://www.codacy.com/public/prantlf/grunt-mdoc)
[](http://gruntjs.com/)
[](https://www.npmjs.com/package/grunt-mdoc)
This module provides a grunt multi-task generating HTML documentation from
Markdown sources using [mdoc].
## Installation
You need [node >= 0.10][node], [npm] and [grunt >= 0.4][Grunt] installed
and your project build managed by a [Gruntfile] with the necessary modules
listed in [package.json]. 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:
```shell
$ npm install grunt-mdoc --save-dev
```
## Input
Store your written articles in to a folder (input), specify a target folder
for the generated HTML pages and optionally a title page (index.md):
```text
input/
overview.md
...
output/
assets_/
index.html
overview.html
...
index.md
Gruntfile.js
```
## Configuration
Add the `mdoc` entry with the mdoc task configuration to the options of the
`grunt.initConfig` method:
```js
grunt.initConfig({
mdoc: {
dist: {
src: 'input',
dest: 'output',
options: {
indexContentPath: 'index.md',
baseTitle: 'My Project Documentation'
}
}
}
});
```
The supported options are:
* `src` : (required) the source folder with files in the Markdown
format; sub-folders will be searched recursively
* `dest` : (required) the target folder for the HTML files
* `indexContent`: (optional) HTML markup to put to the top of the index
page; it takes precedence over `indexContentPath`
* `indexContentPath` : (optional) Markdown source file for the index page
* `baseTitle` : (optional) the title text for the HTML page head
* ... refer to the [mdoc] documentation for all the available options
Then, load the plugin:
```javascript
grunt.loadNpmTasks('grunt-mdoc');
```
## Build
Call the `mdoc` task:
```shell
$ grunt mdoc
```
or integrate it to your build sequence in `Gruntfile.js`:
```js
grunt.registerTask('default', ['mdoc', ...]);
```
## Notes
The generated `index.html` file should be opened from a HTTP server. The
sidebar that shows the documentation index is loaded by AJAX, which does
not work when the HTML page is opened from the `file://` scheme.
## 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.
## Release History
* 2018-04-27 v1.0.0 Dropped support of Node.js 4
* 2017-02-24 v0.3.1 Update dependencies
* 2016-26-08 v0.3.0 Upgrade to Grunt 1.x
* 2016-03-05 v0.2.2 Update dependencies, improve build testing
* 2015-01-31 v0.1.1 Initial release
## License
Copyright (c) 2015-2019 Ferdinand Prantl
Licensed under the MIT license.
[node]: http://nodejs.org
[npm]: http://npmjs.org
[package.json]: https://docs.npmjs.com/files/package.json
[Grunt]: https://gruntjs.com
[Gruntfile]: http://gruntjs.com/sample-gruntfile
[Getting Gtarted]: https://github.com/gruntjs/grunt/wiki/Getting-started
[mdoc]: https://github.com/millermedeiros/mdoc