build a minimalist site for your documentation

This module generates a documentation site from two simple components:

1. A collection of markdown documents
2. A hierarchical object specifying your table of contents

This module is intentionally simpler and more opinionated than something like Jekyll or Sphinx. Depending on what you're looking for, that might be good, because it's easier to reason about, or bad, because it's less flexible! It'll probably be most useful if your documentation already consists entirely of markdown files, and it composes well with any tools that generate markdown, for example ecosystem-docs, which pulls README files from a collection of GitHub repositories.

Sites can be built using a command-line tool, or using the library as a module with browserify. There are options for specifying a project logo, custom css, and other basic formatting. Support for themes coming soon!

PRs welcome!

live demo

Install as a command-line tool

npm install -g minidocs

Add to your project with

npm install --save minidocs

Just specify the location of your markdown files, the table of contents, the output location, and build the site

minidocs docs/ --contents contents.json --output site/

The folder site will now contain the html js and css for your site.

Specify a table of contents

var contents = {
  'overview': {
    'about': 'about.md'
  },
  'animals': {
    'furry': {
      'sheep': 'sheep.md'
    },
    'pink': {
      'pig': 'pig.md'
    }
  }
}

Then build the site and add it to the page with

var minidocs = require('minidocs')
var include = require('include-folder')

minidocs({
  contents: contents,
  markdown: include('./markdown')
})

This assumes you have the files about.md, sheep.md, and pig.md inside a local folder markdown.

To run this in the browser you'll need two browserify transforms:

• folderify, to transform the call to the include-folder module into an object with all your markdown files
• brfs, to transform fs.readFileSync('./styles.css') into a string with the contents of that file

To run a full example, clone this repository, go into the folder example then call

npm install
npm start

Usage:
  minidocs {sourceDir} -c {contents.json} -o {buildDir}

Options:
  * --contents, -c     JSON file that defines the table of contents
  * --output, -o       Directory for built site [site]
  * --title, -t        Project name [name of current directory]
  * --logo, -l         Project logo
  * --css              Optional stylesheet
  * --help, -h         Show this help message

Where opts is an object that can specify the following options

• contents object with the table of contents, required
• documents array of markdown files, required
• styles a stylesheet, if not required will only use base styles
• logo relative file path to a logo file, if unspecified will not include a logo
• initial which document to show on load, if unspecified will load the first document
• root a DOM node to append to, if unspecified will append to document.body

MIT