The configuration file is an essential part of the static website that will be built. It tells the builder what template to use, what information to display, and what defaults to apply.

By default the configuration file should be named markdown-docs.js and should reside in the root of your source directory.

Example Configuration File

module.exports = {
  page: {               // set page defaults
    layout: 'default',
    toc: true
  },
  site: {               // set site wide information
    editSourceUrl: 'https://github.com/<my-org>/<my-repository>/tree/master/docs-src',
    title: 'Markdown Docs',
    url: 'https://<my-org>.github.io/markdown-docs/',
  },
  template: {           // set template specific information
    path: 'default',
    cssVars: {
      brandColor: '#00A288',
      brandColorLight: '#8BDBCD',
      brandColorDark: '#00382F'
    }
  }
}

Common Configuration File Options

Page Options

The configuration options that are specific to pages exist in the page object.

These options act as defaults for the pages and can be overwritten in the page headers for any page.

Code Snippit 
module.exports = {
  page: {               // set page defaults
    layout: 'default',
    toc: true
  },
  ...
}
Option Description
layout The template layout to use to render the page.
toc The default table of contents setting.

Site Options

The configuration options that are general to the entire site exist in the site object. Whichever template layout you use should use these values to render each page.

Code Snippit 
module.exports = {
  ...
  site: {               // set site wide information
    editSourceUrl: 'https://github.com/<my-org>/<my-repository>/tree/master/docs-src',
    title: 'Markdown Docs',
    url: 'https://<my-org>.github.io/markdown-docs/',
  },
  ...
}
Option Description
editSourceUrl The base URL of where the user could go to edit the online copy of the source directory. If this is omitted then the template should know to exclude this information from the rendered page.
title The title for the website.
url The URL of where to see the rendered website.

Depending on the template layout being used, additional site properties may be used to render the page.

Template Options

The configuration options that are specific to a template reside here. Most of these options will only be used by the template layout, the exception being the path and cssVars.

Code Snippit 
module.exports = {
  ...
  template: {               // set template specific information
    path: 'default',
    cssVars: {
      brandColor: '#00A288',
      brandColorLight: '#8BDBCD',
      brandColorDark: '#00382F'
    }
  }
}

Depending on the template layout being used, additional site properties may be used to render the page.

Option Description
path The path to a custom template to use or the name of a built in template. default is a built in template.
cssVars An object used to modify the CSS for a template (and thus the look of the template). Each template defines its own CSS variables that can be overwritten.

Configuration File Location

Your documentation can use a custom config file instead of always using the markdown-docs.js file. This could be useful if you have different settings for development and production documentation.

You can specify which configuration file to use either through the command line or through use of this library in your own code.

Build with Custom Config File Location

Command Line

$ markdown-docs build -c ./source/my-config.js ./source ./destination

Code

const markdownDocs = require('markdown-docs')
const promise = markdownDocs.build('/path/to/source', '/path/to/destination', {
  config: '/path/to/my-config.js' 
})

Develop with Custom Config File Location

Command Line

$ markdown-docs dev -c ./source/my-config.js ./source ./destination

Code

const markdownDocs = require('markdown-docs')
const promise = markdownDocs.dev('/path/to/source', {
  config: '/path/to/my-config.js' 
})