Beautiful docs

Beautiful docs is a documentation viewer based on markdown files.
Documentation manuals can be described in a manifest file using JSON. It can also generate static pages.


Checkout for an example or github for the sources.
You can find a screenshot of the generated doc here.

Install using npm:

npm install beautiful-docs


Manifests are not mandatory but they allow to specify custom options for your documentation.
A manifest file contains a JSON object with the following properties:

Files can be absolute URIs, relative to the rootDir option or relative to the manifest file. Example:

    "title": "Beautiful Docs",
    "files": [""]


bfdocs [--option1=value [--option2=value ...]] [/path/to/manifest.json] [/path/to/output/dir]

Available options:

Default output dir is ./out.
You can specify the path to a directory containing markdown files (*.md) instead of a manifest file

Default theme

The default theme adds the following options to your manifest.json file:

The theme has a search capability. It will generate a search index at compile time and you will be able to search your documentation without the need of a server. Everything is done client side!

You can use the following css classes to style your documentation (suround a block with a div tag):

Tables will be automatically formated.

Theming and static pages generation

Beautiful Docs makes it very easy for you to create your own theme. A theme is made of 2 templates:

A few variables are available inside your templates:

The Manifest object has some interesting properties:

Similar to Jekyll, files can have a header enclosed in ---. If such a header is found, the file will be rendered using eco, Beautiful Docs' rendering engine. The header is a YAML blurbs. All properties will be available as variables when rendered.

The special layout property allows your to wrapped the rendered content of the current file inside a layout. It must be a filename relative to the theme path.

Templates have access to the @include(filename) function to include files. The filename must be relative to the current template filename.

All other files in the theme folder are copied over to the output directory. Less and Coffee files will be automatically converted. All files starting with an underscore will be ignored.


layout: _layout.html
My custom page for <%= @manifest.title %>

Beautiful Docs comes with 2 themes: default and minimal. Have a look at them in the src/themes folder to learn more about creating your own theme.

Multiple manifests

Beautiful docs can handle multiple manifests at once and generate and index file to easily access each of them.

bfdocs [options] [--manifests-only] /path/to/first/manifest.json /path/to/second/manifest.json /path/to/third/manifest.json [/path/to/output/dir]

If you have more than one manifest and you don't want to specify the output dir, you must use the --manifests-only option.

When multiple manifests are specified, each generated ones will be located in its own subfolder.

You can also generate the index file on its own using --index-only:

bfdocs --index-only /path/to/manifest.json /path/to/manifest.json index.html