customizing

The html generator allows you to completely customize the look and behavior of the site. You can also supply your own generators to build other forms of documentation.

Customizing the default HTML generator

You can customize the templates and helpers used to render a docObject and customize the JavaScript and CSS used by the HTML pages. This behavior is controlled mostly by the siteConfig's templates and static options. However, some tags like @hide allow you to alter the behavior slightly.

Changing the HTML

The html generator uses Handlebars templates and helpers to render docObjects. Overwrite the default templates with the siteConfig templates option. If you are producing a multi-versioned site, and you want all versions to have the same template, your website's documentjs.json might look like:

{
  "versions": { ... }
  "siteDefaults": {
    "templates": "theme/templates"
  }
} 

The templates path should be specified relative to the documentjs.json folder.

This will use the templates (and helpers) in "theme/templates" to overwrite the default helpers and templates. The default templates can be found in documentjs/site/default/templates.

documentjs/site/default/templates has the following templates:

• layout.mustache - Contains the outer most content that is the same on every page. The page's script tags are loaded here.
• content.mustache - Rendered within layout.mustache. It calls out to all other templates as partials.
• menu.mustache - The sidebar menu.
• active-menu.mustache - The part of the sidebar menu that shows the children of the active item.
• signature.mustache - Shows a "signature" block. A signature block for a function has the signature of the function and the params listed within it.
• title.mustache - The header of each rendered page.
• types.mustache - Given a valueData, iterates through each of its types and creates a signature with it.

For example, to make a change to the layout, copy documentjs/site/default/templates/layout.mustache to theme/templates and make changes in your copy.

Adding Helpers

You can add and use your own Handlebars helpers by creating a .js file in your templates directory. For example, you can create theme/templates/helpers.js. Any .js file will be required as a module with CommonJS. The module is expect to export a makeHelpers function like:

// theme/templates/helpers.js
module.exports = function(docMap, options, getCurrent){
  return {
    "hello-world" : function(){
      return "Hello World!"
    }
  }
};

This allows you to write {{hello-world}} and get back:

Hello World!

This behavior is provided by generators.html.build.helpers.

Changing static resources: Styles, Images, and JavaScript

The html generator builds a static distributable that includes the CSS, Images, and JavaScript used by the site. The default content used to build the site can be found within documentjs/site/default/static.

You can overwrite the default static content with the siteConfig static option. If you are producing a multi-versioned site, and you want all versions to have the same static content, your website's documentjs.json might look like:

{
  "versions": { ... }
  "siteDefaults": {
    "static": "theme/static"
  }
} 

After the default and static content have been combined, the static/build.js file is required with CommonJS and run. static/build.js is expected to export a builder function that builds the final static content and copies it to a distributable location.

The default builder uses StealJS to build a CanJS and LESS application. It copies the minfied css and js bundles as well as all files in the static/fonts, static/img, and static/templates folder to the distributable location.

It's likely you don't have to write a custom builder and can instead overwrite the default CSS, Image, and JS files used by the builder.

Changing Styles

documentjs/site/default/static/styles contains the default styles. The styles are broken down functionally:

• styles.less - Loads all styles.
• variables.less - Configuration of colors and image location variables.
• icons.less - Classes set up for icon usage.
• api.less - Styles for the main content area.
• base.less - Styles for html tags, sans typography.
• typography.less - Styles for all text.
• brand.less - Styles for the logo .brand class.
• code.less - Styles for code blocks.
• ie.less- If internet explorer is used, this style is used.
• layout.less - Styles for the layout.mustache template.
• helper.less - Helper classes to control layout.
• reset.less - A css reset.
• sidebar.less - Styles for the sidebar.
• buttons.less - Styles for the default button.

To change the default styles, copy one of the less files above to your siteConfig.static's styles folder and make changes.

Changing Colors

To change colors, copy variables.less and change the color palette options:

 @haze: ##cccccc;

Below the color palette definitions, you can see how they are mapped to parts of the application.

Adding other styles

To add another style, create the less or css file in your siteConfig.static's styles folder. Then, copy styles.less and import your stylesheet:

@import 'ie.less';
@import 'mystyles.less'

Changing Images

To change the default images, add your replacement images to siteConfig.static's img folder. You probably want to create a:

• img/logo.svg - Your project's logo.
• img/logo-grey.svg Your project's logo in greyscale.

Changing JavaScript

The default builder loads and builds the documentjs/site/default/static/static.js file using StealJS. This imports various modules and initializes their behavior. StealJS supports importing ES6, AMD, and CJS modules. To add your own behavior:

1. Add your JavaScript files to the siteConfig.static folder.

2. Copy documentjs/site/default/static/static.js to siteConfig.static folder.

3. Edit your copy of static.js to import and initialize your JavaScript code:

    steal(
      "./your_module.js"
      "./content_list.js",
      "./frame_helper.js",
      "./versions.js",
      "./styles/styles.less!",
      "./prettify",function(YourModule, ContentList, FrameHelper, ...){
        // call your module
        YourModule()
        // leave the rest of the code
        var codes = document.getElementsByTagName("code");
        ...
    });
   

Writing your own generator

You can create your own generator module which gives you complete control over how a docMap is converted to some output.

If you do decide to create your own generator, the best place to do that is within its own project that is registered on npm. To do that, create a github project with a main.js that exports a generator function like:

var Q = require('q'),
    fs = require('fs'),
    writeFile = Q.denodify(fs.writeFile),
    path = require('path');
    
module.exports = function(docMapPromise, options){
   return docMapPromise.then(function(docMap){
     return writeFile(
         path.join(options.dest,'docMap.json'), 
         JSON.stringify(docMap) );
   });
};

Publish this to npm. For this example, we'll assume it's published as "doc-map-json".

In a project that wants to use this generator, make sure it's listed as a devDependency in package.json:

{
  ...
  "devDependencies": {
    "documentjs" : ">0.0.0",
    "doc-map-json": ">0.0.0"
  }
}

In documentjs.json, make sure to list that generator and any options it needs in your siteConfigs.

{
  "sites": {
    "api": {
      "generators": ["html","doc-map-json"],
      "dest": "docs"
    }
  }
}