⚠️ Unmaintained.

---

apidoc-seed

A boilerplate project for quickly getting your RAML documentation published.

Live Site

This is a generator that compiles Markdown and RAML files into a static site. The following Node.js stack is used:

• Build tasks using Grunt
• Content assembling with Metalsmith
• Templating using Jade
• CSS-preprocessing with Stylus
• Basic styling using Twitter Bootstrap

Note that apart from Markdown support within the RAML spec it also supports plain .md files that are compiled independently from the API documentation.

Quickstart

Prerequisites

• Make sure Node.js is installed and in your PATH
• Install Grunt: npm install -g grunt-cli

Installation

1. Clone the repo: git clone https://github.com/lotaris/apidoc-seed.git
2. Open the folder: cd apidoc-seed
3. Install dependencies: npm install
4. Run the dev server: grunt dev --private=true
5. Open a browser at http://localhost:7000/

Documentation

This boilerplate project documents itself. Checkout the HOWTO section at the Live Site.

Build Options

If you're building for production, there are a few more options you can speficy when compiling the documentation.

Private vs. Public

It's possible to mark parts of your content as private which results being discarded depending on how you compile the documentation. In order to build in private mode (like the live site), use --private=true when building. For more information, see Private Content.

Production Builds

In production you might want to have your Javascript and CSS minified and concatenated. Also your final documentation site might be sitting in a different context root of your web server.

In order to build for production with assets minified, run

grunt prod --minifyAssets=true

If you're building for a different context root, run

grunt prod --minifyAssets=true --baseUrl=/foobar

You can use two different presentation for the JSON Schema representations. You can use a bordered indented schema or a border less indentation schema. For that, you can specify the option

grunt dev|prod --schemaIndentBordered=false|true

During the time you are writing the documentation, you probably want to see everything without having to click and click again on the page. Therefore, you can use the devMod option to collapse in all the collapsable elements. For that, use the following option. Pay attention this option is different from grunt dev. The dev mode can be used when building API doc for prod.

grunt dev|prod --devMode=true|false

Other Goals

There are a few more Grunt tasks that can make your life easier:

• grunt build builds the site and exits. Assets are not minifed.
• grunt serve launches a local webserver and serves a previously built site at http://localhost:7000/.

Credits

To Kevin Renskers for his excellent raml2html. Although this project doesn't make use of raml2html directly, the included HTML template for the compiled documentation is derived from it.

License

MIT, see LICENSE.