A complete documentation generation tool for Markdown files
What's black and white and read all over?
- Markdown syntax using NAMP.
- Support for content references (conrefs) in Markdown
- Pass in individual files or entire directories; exclude files and directories with glob matching
- Embeddable metadata
- Easy template customization
- Automatic linking for all heading tags (
h2, e.t.c.), as well as automatic table of headers generation
- Provides a JSON format
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
That'll turn this README into a better looking HTML file in the /out directory.
panda-docs in a script! Simply define a file similar to this one:
var options =title: "Panda (from script)"pandamake"./src/" optionsif errconsole.errorerr;;
You can find out more information on options you can use below:
There are a number of arguments you can pass to Panda that affect the entire build. They are:
-h, --help` Show this help message and exit.
--versionShow program's version number and exit.
--output PATHResulting file(s) location [out]
--outputAssets PATHResulting file(s) location for assets [out/assets]
,--title STRING` Title of the index page [Panda: Default Title Here]
--skin PATHThe location of your Jade templates [./templates/default]
--disableTestsDisables the test suite that runs at the end of an HTML build. This is NOT recommended.
--keepFirstHeaderIf set, keeps the first header (
--baseUrl STRINGBase url of all links [./]
--keepOutDirDoes not wipe output directory before building (defaults to
--safeWordsAn array of words not to complain about when performing a spellcheck test
You need at least one Jade template
layout.jade. Optional you can
have a template per file, for example if you have the file
you can add
index.jade to your template folder and it will be used
only for this file.
Within your Jade template, you have access to the following variables:
contentis the transformed HTML content of your Markdown file
metadatais an object containing your document-based metadata values
manifestis an object containing the Manifest.json properties
tohis an object containing the headings for each file (
h2, e.t.c.). See below for more information on this object.
headingTableis a function you can use to generate a list of your page's table of contents. See below for more information on using this
fileNameis the name of the resulting file (without the extension)
titleis the title of the documentation
pageTitleis the title of the current page
mtimeindicates the last modified time of your source file
markdownreferences the Markdown converter; since this is based on namp, you'll want to add
.htmlat the end to get the actual HTML
All your passed in
options are also available.
toh object has the following structure:
h1 header is also automatically an anchor. The resulting HTML for an H2 called "Testing Your Highlighter" looks like this:
Testing Your Highlighter
You can add an icon for
headerLinkIcon to make it more discoverable, i.e. by using something from Font Awesome.
Finally, you also have access to a function, called
headingTable, that automatically generates a table of contents for each page's heading. The resulting HTML produced by this function might look like this:
Defining a ModeDefining Syntax Highlighting RulesDefining TokensDefining Regular ExpressionsGroupingsDefining StatesCode Folding
Basically, every sub-heading is nested underneath a parent heading of larger size. In the example above, we have a page with an
<h2> tag called "Defining a Mode", followed by another
<h2>, "Defining Syntax Highlighting Rules", which itself is followed by two
<h3> tags, "Defining Tokens" and "Defining Regular Expressions." The last
<h3> has an
<h4> called "Groupings." We then go back to some regular old
This generated table always ignores the
<h1> tag. You can customize it by by embedding the following signature into your Jade template:
headingTabletoh maxLevel classes
tohis your page's
maxLevelis optional, and refers to the maximum heading number you want to display; this defaults to 4. Basically, any
htag greater than this number is ignored
classesis optional, and it's an array of two strings. The first is a class that applies to all the
<ol>tags; the second applies to the
<li>automatically gets a
level_<POSITION>class that is set to the current item's position
Thus, to generate the above, your Jade template might go:
!= headingTable(toh, 5, ['tocContainer', 'tocItem'])
The callback for
panda returns a JSON with one key:
files, which is a listing of all the files generated.
files is an array of objects, containing the following keys:
filename: the filename (minus the suffix)
mtime: the last modified time of your source file
pageTitle: the title of the page (text only, meaning minus any
You could use this information to provide a list of Recently Updated content--which is exactly what the Cloud9 IDE User Documentation does.