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.
- 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:
, andWarning:
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)
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.
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:
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 filesresources
: 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 pagecodeHighlightTheme
: 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
: Theusername/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-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
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 filemetadata
is an object containing your document-based metadata valuesmanifest
is an object containing the Manifest.json propertiesoptions
is an object containing your passed in propertiesfileName
is the name of the resulting file (without the extension)title
is the title of the documentationwhoAmI
is the full path name of the source filemarkdown
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.