Pretty Awesome (and Necessary) Documentation Assembly--A total documentation build system for technical writers, and those who want to be like them.
JavaScript
Switch branches/tags
Nothing to show
Pull request Compare This branch is 45 commits behind gjtorikian:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
lib
resources/images
src
templates/default
.gitignore
.npmignore
LICENSE
README.md
build.js
index.js
package.json

README.md

Panda Docs

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

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-docs src/manifest.json 

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

Usage

panda-docs </path/to/manifest.json> _[options]_ 

The manifest.json file is mandatory, and all other options are optional. The default output directory here is ./out.

If you'd like to use panda-docs in a script, you can! Simply define one like this:

var panda = require("panda-docs");

panda.make(["./src/manifest.json", "-t", "Panda (from command line)"], function(err) {
    if (err) console.error(err);
});

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.

  • files: An array defining the path to your files
  • resources: An array of directories to also copy into the /out directory. This is usually used for accompanying or inline images.
  • 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
  • -o, --output: Resulting file(s) location [out]
  • --outputAssets: Resulting file(s) location for assets [out/assets]
  • -t, --title: Title of the documentation [Panda: Default Title Here]
  • --template: The location of your Jade templates [./templates/default/layout.jade]. Though the path is optional, you must have a valid Jade template somewhere.
  • --assets: The location of your assets (CSS, Javascript) [./templates/default/assets].
  • --noheader: Hides the header
  • --notoc: Hides the table of contents sidebar
  • --baseurl : Base URL of all links

Jade templates

You have to specify at least one Jade file as a template for your pages. 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
  • fileName is the name of the resulting file (without the extension)
  • title is the title of the documentation
  • whoAmI is the full path name of the source file
  • markdown is a function you can use to make a call out to the Markdown processor. For example, you can use it like this in your template:
p	
    != markdown("This is _going_ to be represented as `Markdown`").html

Don't forget that Namp returns an object, so you'll need to add that .html at the end.