A Taste of FruitJS

By Andrew Hushbeck

FruitJS (pronounced Fruit Juice) is a new Node.js utility for writing your technical documentation in Markdown and compiling to an easy to use HTML site. You can install and use FruitJS through npm and the command line utility, or by grabbing the source yourself at https://github.com/ktsashes/fruitjs. The project was built with the goal of making it simple and quick for both technical and non-technical people to get beautiful and useful documentation up quickly. In addition to this, it allows documentation to be on Github (and rendered nicely there) as well as on its own site, which will ensure it is easy to find.

This article will walk you through how to use FruitJS and a little about how it was built.

Getting Started

Compiling your documentation is meant to be as dead simple as possible. Once you’ve written your documentation, simply do the following:

1. If FruitJS is not installed, you’ll want to run npm install –g fruitjs via the command line.
2. You’ll want to make a small JSON file describing what pages you’d like to include, and in what order. Save that in the directory alongside your Markdown. It will look something like this:

   {
       “pages”: [“page1.md”, “page2.md”]
   }

3. Then run the script via the command line using fruitjs manifest.json

Your site should be rendered into a subdirectory within the current directory named “output.” There are flags and options available in the command line to change where FruitJS outputs or to render everything on a single page. You can also specify images, LESS, CSS and JavaScript files to include on and customize your pages. You can check out the full documentation (rendered with the script of course) on https://ktsashes.github.io/FruitJS/.

Making FruitJS

When building a Node app like this, basic building blocks are the most important things. The first thing to do was research what modules existed that I could take advantage of. First, and most obviously, was finding a good module for converting Markdown to HTML. I could have ported the Markdown compiler myself, but standing on others shoulders is much easier.

Depending on 3rd Party Libaries

The code was originally written using the Node module “markdown,” but because of a poor middle representation, I switched to using marked. I needed a parser that was flexible enough to handle Github flavored Markdown, but I also needed an intermediate representation that I could run through in JavaScript. Marked offered both of these, and was pretty simple to use.

One interesting thing I found was that the library had some pull requests for features I needed to work properly. It’s tough when your module isn’t quite what you need, and I found I really had two choices. The first was to try and find a different module to use that had all the bells and whistles (or, failing that, write one) or to make the modifications myself. I actually opted for making the modifications myself and including the source in my package. The npm package format has an option to specify you are controlling the versioning of a particular dependency manually, and I ended up making another change or two to help myself out in the long run. A little bit more overhead, but a customized tool works a lot better than none at all.

After the major module, most of the other things I needed were pretty straightforward. Because file actions are asynchronous, and callbacks and streams aren’t much fun, I opted to use RSVP to add promises to the system. I used Underscore for templating, and LESS for CSS support. Optimist is good for command line arguments, and mkdirp is a nice utility for writing files, so those got thrown in as well.

Adding Extensibility

When writing the rest of the module, I had two major goals. The first was to make it as easy as possible to go from Markdown to HTML. One simple command should be enough. My second major goal was to make it easy to make your docs your own. So, right from the start, I’ve been working on integrating a template system with extensibility so that if you don’t like the style, you can pick another, or make your own. With all that in mind, I came up with a one line command, a manifest file, and the ability to add images, CSS, and JavaScript to your HTML.

More FruitJS

If you take a look at the docs, there are a few things you might notice. Things are a little sparse at the moment. There are no templates other than the default, your manifest file gets long quickly, and there isn’t really support if you want to have a custom menu. All of the support for this is planned, but not quite finished yet.

My goal is to allow you to get the documentation you want by simply going to the command line and saying fruitjs. Templates, assets, custom menus, and making the manifest optional are all planned on the way for the 1.0 release (currently we’re at 0.6.1). So look forward to more coming soon, and if you have ideas you’d like to see, feel free to add them to the Github, or hack away yourself.