grunt-mkdocs

Grunt plugin generating documentation web site from Markdown sources using mkdocs

Getting Started

You need node >= 0.8, npm and grunt >= 0.4 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:

$ npm install grunt-mkdocs --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-mkdocs');

The "mkdocs" tool

This plugin depends on the mkdocs documentation web site generator, which can produce HTML files and other assets suitable for upload to the Read The Docs web site. You must install it before you build the documentation.

You need Python and pip installed, then you install the mkdocs package:

$ sudo pip install mkdocs

Input

Store your written articles in to a folder (docs) and specify a target folder for the generated HTML pages (site); the index.md file will become the title page:

docs/
  index.md
  overview.md
  ...
site/
 overview/
 index.html
 ...
mkdocs.yml
Gruntfile.js

The "mkdocs" task

This module provides a grunt multi-task generating HTML documentation from Markdown sources using mkdocs. In your project's Gruntfile, add a section named mkdocs to the data object passed into grunt.initConfig().

grunt.initConfig({
  mkdocs: {
    dist: {
      src: '.',
      options: {
        clean: true
      }
    }
  }
})

All documentation project options should be maintained in the mkdocs configuration file (mkdocs.yml) in this plugin version.

Options

src

Type: String Default value: '.'

Path to documentation root directory with the mkdocs.yml file.

options.clean

Type: Boolean Default value: false

Removes stale files (from previous builds) from the target folder.

Build

Call the mkdocs task:

$ grunt mkdocs

or integrate it to the default build sequence in the Gruntfile:

grunt.registerTask('default', ['mkdocs', ...]);

Notes

If you want to browse the generated web site from the file system (using the file:// scheme), add the option use_directory_urls: false to the mkdocs.yml configuration files. The generated links will point to .../index.html files instead of just .../ directories relying on the default documents supported by the web servers.

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
• 2016-02-24 v0.2.3 Upgrade dependencies
• 2016-26-08 v0.2.0 Upgrade to Grunt 1.x
• 2015-07-30 v0.1.0 Initial release

License

Copyright (c) 2015-2019 Ferdinand Prantl

Licensed under the MIT license.