panda-docs

A complete documentation generation tool for Markdown files

Panda

A total documentation build system for technical writers, and those who want to be like them.

What's black and white and read all over?

This is a documentation build system that takes Markdown files as sources, and produces HTML files. It runs on Node.js, and uses Jade as its templating engine.

A lot of the concepts are based on maximebf's "beautiful-docs", but there are so many differences--the most notable being that this is in Javascript, not Coffeescript--that I decided to turn it into a complete fork.

Make sure you have a recent build of Node.js (this was tested on v0.6.0). Install it using npm:

npm install panda-docs -g

Want to try a demonstration? Then clone this repository, and run

node bin/panda src/manifest.json 

That'll turn this README into a better looking HTML file in the /out directory.

panda _[options]_ [/path/to/manifest.json] _[/path/to/output/dir]_

Of these, [options] and [/path/to/output/dir] are optional--but the manifest.json file is mandatory. The default output directory here is ./out.

You can find out more information on options you can use below:

A manifest file is a mandatory JSON file that indicates where your source files reside, as well as specifing customization options for your documentation pages.

A manifest file can have the properties listed below. All the properties are optional, with the exception of files.

  • title: The title of the documentation (defaults to "Documentation")
  • files: An array defining the path to your files
  • extension: The extension of your Markdown files. Some people use .md, others .markdown, and still others .text. This is optional, and defaults to .md.
  • home: The file to display as the manual homepage (this won't show up in the TOC)
  • category: Category of the manual (used on the homepage) (defaults to nothing)
  • css: An absolute URL to a CSS stylesheet that will be included in every page
  • codeHighlightTheme: The name of the highlightjs theme to use for code highlighting (defaults to 'github')
  • embedly: Activate embedly by passing in your API key. Links to embedly must be placed alone in a paragraph.
  • github: The username/repo on GitHub that's used to link through with the "Fork me on Github" banner. If this is omitted, then there's no banner.]

As noted above, files can either be absolute URIs, or relative to the manifest file. For example:

{
    "files": ["README.md", "../../someFile.md"]
}

There are a number of arguments you can pass to Panda that affect the entire build. They are:

  • -h, --help: Display the help information
  • -t, --title: Title of the page [Panda: Default Title Here]
  • --template: The location of your Jade templates [_./templates/default_]. You should set this.
  • --assets: The location of your assets (CSS, Javascript) [_./templates/default/assets_]. You should set this.
  • --noheader: Hides the header
  • --notoc: Hides the table of contents sidebar
  • --baseurl : Base URL of all links

You'll must have at least one Jade file called layout.jade in your /templates directory. This acts as the base template for all your generated files.

Within your Jade template, you have access to the following variables:

  • content is the transformed HTML content of your Markdown file
  • metadata is an object containing your document-based metadata values
  • manifest is an object containing the Manifest.json properties
  • options is an object containing your passed in properties