NapiDocs is a set of Node.js command line scripts that transform a directory of Markdown files and supporting resources into a static HTML site pages documenting a REST-style service.
Before you begin iterating on your documentation, you'll need to:
git clone https://github.com/mweagle/napidocs.git ~/napidocs
cd ~/napidocs
npm install
Then you can start to write your documentation:
node napidocs.js init -t ~/NapiDocs
/_static
: Static resources (CSS, JS) that will be copied to the target output/build
: The built output that should be statically hosted./docs
: The tree of Markdown files that comprise your service's documentation./plugins
: Plugins used to transform the internal documentation tree to HTML output. Plugins are referenced in the /template/api.html
file./template
: Includes the api.html
file that is used to generate each documentation page.node napidocs.js preview -s ~/NapiDocs
-p/--port
command line argument/template/api.html
:
/docs
child directories are transformed into Group headers in the sidebar. Delete any immediate directories that don't apply to your service.node napidocs.js build --source ~/NapiDocs
~/NapiDocs/build
) on a static server.
If you want to customize the output, you can write a custom plugin and reference it in /template/api.html
. For example:
<ul class="nav nav-list">
<%= my_custom_plugin %>
</ul>
will instruct NapiDocs to look for ~/NapiDocs/plugins/my_custom_plugin.js
in the documentation directory.
Plugins must export a single function:
/**
* Return HTML for the given asset object
* @param {String} url_prefix The URL prefix to use in HREFs. Will *always* end in a trailing forward slash.
* @param {Object} asset_obj The current asset being rendered (Markdown or directory)
* @param {Object} parent_obj The parent asset of asset_obj, may be null/empty
* @param {Object} all_data The entire accumulated internal documentation representation
* @return {String} HTML content
*/
module.exports = function(url_prefix, asset_obj, parent_obj, all_data)
{
// Return HTML string
}
The internal representation is visible by providing the -d/--dump
command line
option to the node napidocs.js build
command.