Panda-docs NPM

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?

Panda reading a newspaper

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.

Features

Markdown syntax, the NAMP module. NAMP supports: The standard Gruber syntax The GitHub Flavored Markdown syntax (including language-specific codeblock fences) The PHP Markdown Extra syntax Maruku meta-data support Support for content references (conrefs) in Markdown Inline metadata support (something Maruku does not do) Strikethroughs Conversion of Note:, Tip:, and Warning: blocks into Twitter Bootstrap alert blocks * Build-time highlighting of <pre> code blocks For more information, check out the NAMP documentation.
Pass in individual files or entire directories
Embeddable metadata
Easy template customization (via Jade)

Installation

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.

Usage

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:

Manifest Files

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"]
}

Options

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

Jade templates

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: