This module is a plugin for Grits.js, a static content builder that's designed for ease-of-use. It provides helpers, layouts, partials, and other resources for authoring documentation-like websites quickly and easily.
This module is still a work in progress and should be considered as experimental. Meaningful documentation is still on the to-do list.
Barring any prerequisites, NPM should be all that you need:
# Global Install
npm install -g grits grits-plugin-docs
# Project Install
npm install --save grits grits-plugin-docs
grits -v --plugin grits-plugin-docs .
{
"plugins": {
"grits-plugin-docs": { ..docConfig.. }
}
}
require("grits");
var grits = new Dasix.grits.Renderer({
"plugins": {
"grits-plugin-docs": docConfig
}
});
require("grits");
var grits = new Dasix.grits.Renderer();
grits.use("grits-plugin-docs", docConfig);
There are some subtleties with loading plugins, but they're beyond the scope of this document; see the Grits.js module and its documentation for more info.
Find information about built in helpers here.
You can configure certain aspects of the grits-plugin-docs
plugin by using a Grits
configuration file. You must point Grits to the configuration file using the --config
CLI option.
conf/grits.json
{
"verbose" : true,
"autoClean": true,
"plugins" : {
"grits-plugin-docs" : {
}
}
}
You can set the "Site Title", which is shown in the top-left of the navbar, by
providing a site-name
setting in your config file.
Example:
{
"plugins" : {
"grits-plugin-docs" : {
"site-name": "Grits:Docs"
}
}
}
Set your branding images for printouts with the print-title-logo
and print-header-logo
options in the plugin config. Currently, the print-header-logo
is only useful if
you are also using the grits-plugin-pdf
plugin.
You can set the "Site Title", which is shown in the top-left of the navbar, by
providing a site-name
setting in your config file.
Example:
{
"plugins" : {
"grits-plugin-docs" : {
"print-header-logo" : "/images/my-header-image.png",
"print-title-logo" : "/images/my-title-image.png",
}
}
}
You can add custom CSS and JS files to the docs
layout using the layoutConfig
setting.
Example:
{
"plugins" : {
"grits-plugin-docs" : {
"layoutConfig": {
"docs": {
"custom-js": [
"/js/test-custom.js"
],
"custom-css": [
"/css/test-custom.css"
]
}
}
}
}
}
You can add Google Analytics to the docs
layout using the analytics
setting.
Example:
{
"plugins" : {
"grits-plugin-docs" : {
"analytics": {
"ga-tracking-id": "UA-XXXXXXX-X" //Your GA Property Tracking ID
},
}
}
}
This project provides a Vagrantfile
, for use with Vagrant.
With Vagrant installed, you can create a pre-configured
development VM like so:
$ vagrant up
Provisioning of the Vagrant box for development makes use of Luke's Linux Scripts, which provides simple installation scripts for several common applications and plugins.
After the Vagrant box finishes its provisioning process you will need to SSH into the VM. You can do this using your favorite SSH client (such as Putty) or using the built-in SSH that Vagrant provides:
$ vagrant ssh
Every command available is defined in package.json
under the scripts
object.
You can execute those scripts using npm run-script
, like this:
[root@grits-doc vagrant]# cd /project
[root@grits-doc vagrant]# npm run-script live
The command above will run with live
script. It and the other useful commands
are described below.
The grits
command will launch Grits.js, which will render some
test content.
The live
command will launch Grits.js in the watch
and serve
modes after
rendering some test content. The content will re-render
if the test content is updated.
The update-grits
command will update the globally installed Grits application.
The test
command will execute any and all available unit tests, of which there
are currently none (but some will be added in the near future).