Doc MD is a grunt.js plugin designed to take multiple help or guide files, written in markdown, and compile them into a single html help document, complete with a Table of Contents that links the sections of the document. While it would certainly be possible to build a single markdown document, as systems grow in complexity (and their documentation grows along with them), it's often easier to maintain up to date documentation if it's broken up by section. However, no one likes clicking through multiple pages of user guides (especially if a page only has a couple paragraphs). Doc MD solves that problem.
If you don't already have one, set up a "package.json" file in your project directory. You can use npm do this if necessary by running npm init
and following the prompts, or by using an editor to create it.
This plugin requires Grunt 0.4 or greater. If you don't already have it, from in your project directory run
npm install grunt --save-dev
This will install grunt and update the devDependencies
property in your package.json file.
Then run
npm install ${path-to-docmd} --save-dev
where ${path-to-docmd}
is the path to a location where you've cloned Doc MD. (At some point once it's more stable, we'll publish Doc MD to the npm registry, and you'll be able to install it more easily.)
Add to your Gruntfile.js
(first creating the file in your project directory if necessary):
grunt.loadTasks('${path to docmd}/tasks');
again where ${path-to-docmd}
is the path to the location where you've cloned Doc MD.
You also need to configure the docs
and output
options to point to the location in your filesystem where you've stored your markdown documents (see the Markdown Structure section for details) and to where you want the output from Doc MD to go, respectively. For each html guide you want, you should specify a Doc MD task, with the single property directory
, specifying the path to the guide in question, relative to the markdown directory specified by the docs
option.
grunt.initConfig({
doc_md: {
options: {
docs: "../../documents",
output: "../docs-build"
},
user_guide: {
directory: "user_guide"
}
}
});
Before running grunt the first time, you need to run npm install
from the Doc MD directory, to grab the necessary node dependencies.
Then you can simply define a grunt task that calls the Doc MD plugin. For example:
grunt.registerTask('default', ['doc_md']);
To run Doc MD grunt ${task}
, where ${task} is the name of the task specified above, from the command line. If you've set up and configured everything correctly, your output should appear in the directory specified in the output
option.
The markdown-content directory (or whatever you choose to call it) needs to contain a valid properties.yml file that defines the organization of the final output document and its Table of Contents.
-
name
A properties.yml file should contain, at minimum aname
property, defining the human-readable name for the guide (or section). If this property is used within atoc
element, Doc MD will insert a header into the final html output as well as an element within the table of contents for that name. -
description
A description of the guide. This is currently unused. -
referenceId
In the case of a top-level element, this will be the name given to the guide file. For instances nested within thetoc
element, this will be used as the id of the section in question and can be used within the markup for purposes of linking within the overall document. -
icon
A set of properties which define the icon for the guide. This should at minimum include afile
property which should contain the path to the icon's location within the resources directory. It can also include astyle
property, which can include any valid css property. The icon is placed within a standardtag, so keep that in mind when using styles.
-
toc
This defines the structure to be used when including content within the guide. It's an array of items. Each item needs to define, at minimum afile
property (which should be the relative path to a markdown file) or aname
property (which will appear as the name of the section, in both the table of contents and the main content). It can also optionally contain areferenceId
or its owntoc
property. -
normalizeHeaders
By default, Doc MD will attempt to normalize the headers used throughout the final html document so the header levels are consistent with the structure defined in the table of contents. IfnormalizeHeaders: false
appears in the properties file, Doc MD will not normalize headers.
Given the following directory structure:
- markdown-content
- resources
- icon.png
- guide1
- properties.yml
- section1.md
- section2.md
- section3
- subsection3.1.md
- subsection3.2.md
- section4
- section4.md
- subsection4.1.md
- section5.md
- resources
a properties.yml file could be
name: Guide One
icon:
file: icon.png
style:
height: 32px
toc:
-
file: section1.md
-
file: section2.md
referenceId: section_two
-
name: section3
referenceId: section3
toc:
-
file:subsection3.1.md
-
file:subsection3.2.md
-
file: section4.md
toc:
-
file: subsection4.1.md
-
file: section5.md
Users should also note that the numbers in the example above are for purposes of illustration only--they're not necessary.
Users can define custom stylesheets and JavaScript files to be included in the final document. The cssDir
and jsDir
properties in the grunt config can be set to the directory where stylesheets and scripts are located. The contents of these directories will be concatenated into a single "user.css" and "user.js" files and included in the final document. These properties default to "css" and "js", respectively.