FruitJS

Welcome to the FruitJS Documentation. This is your resource for learning how to use FruitJS, as well as your guide when you forget. And, of course, this documentation is created with FruitJS.

What is FruitJS?

FruitJS (pronounced Fruit Juice) is a documentation generator built in Node. It is meant to be a simple way to write your documentation in Markdown, and have it converted to a nice site easily. Markdown has a lot of niceties in terms of displaying code snippets, and quick edits, but isn't easy for those who are just looking for some technical documentation. That's when a nice API or documentation site is key, and that's where FruitJS comes in. Simply create your pages in Markdown, tell FruitJS how to find it, and sit back as your documentation becomes oh so sweet.

How can I use FruitJS?

I'm glad you're so anxious to dive in. Or at least, I'm glad I could lead you to that. Getting started is pretty simple. Just use npm to install FruitJS, and run it from the command line. You also can require it in a JS file if you'd like to generate things on your own in JS.

npm install FruitJS

From the command line, you can then do the following:

fruitjs manifest.json

Or, if you prefer a script file, something like the following would work best:

var FruitJS = new (require('FruitJS'))("My Documentation");

FruitJS.addPage('my.markdown');
FruitJS.buildMenu().then(
    function () {
        FruitJS.render();
    })
    .then(null,
    function (err) {
        // Error handling goes here
    });

Then you're site is all ready to go. By default we output your site to a folder called output (wild, I know) right in that same folder it was run in.

But what about X?

That's a great question. I have a lot of plans to include many features I feel people will find helpful. I've got plans for extra navigation categories, themes, and a few other things. I've got big plans for what I hope this to be, and I hope to create them as quickly as I can. That said, this is just the beginning. This is the ground floor we're building on here. So there is still a lot of room to grow. If you'd like to suggest features you'd love to see, let me know on the GitHub issue tracker. Or, feel free to fork and go to town on your own.

Command Line Interface

The command line interface is likely the primary interface in which you will work with. It is meant to be as straight- forward as possible, only needing a small json file, and some optional flags and parameters for modifying behavior.

Manifest File

The manifest file is the way to tell what pages you want to compile into your HTML site. It will list pages, assets, images, any extra CSS or JS, and whatever else you want to include. The format is a simple JSON file included somewhere in your folder structure. Any file references in the JSON file should be relative to the manifest files location on disk.

Properties

Name Type Default Description
name String '' The name of your site
pages Array [] An array of markdown pages that will be compiled into HTML. The order of the pages will be preserved as the order in the navigation, with the first item being the homepage.
css Array [] An array of additional CSS files you'd like to include on your pages. All of the CSS files will be added to each page.
less Array [] An array of additional LESS files you'd like to include on your pages. Files will be compiled to CSS and added to each page.
js Array [] An array of additional JS files you'd like to include on your pages. All of the JS files will be added to each page.
images Array [] An array of image files you'd like to include on your pages. Files will be put in the images folder, and can be referred to in your markdown from that folder
imageTitle FilePath null A file path to an image or logo you'd like to display instead of your site name on each page
singlePage Boolean false A flag for if all the markdown should be compiled to a single page.
tocLevel Number 6 Number of heading levels to use in the automatically generated menu

Command Line Arguments

-output FILEPATH or -o FILEPATH

Folder that rendered HTML should be placed into. File path should be absolute or relative to where the script is being run at.

Format

-o export/to/this/folder/
-output "also/works/like this"

-singlePage or -s

Flag that can be set to indicate that output should be on a single page.

Format

-s

Code API

Constructor

Creates a new FruitJS object. This object is the primary object for creating and rendering documentation sites.

Parameters

Required Type Description
Yes String The title of the documentation. This will be used as the title in the browser window and on the page.

Returns

New FruitJS object

Examples

var FruitJS = require('FruitJS');
var docs = new FruitJS("My Documentation Site")

addCSS

Adds a CSS file to the output. This file will be copied over to a css folder in the output directory and will be included on every page.

Parameters

Required Type Description
Yes String The path to the file, relative to where the script is being run

Returns

Returns FruitJS object after adding script to allow chainability.

Examples

docs.addCSS('myStyles.css');

addImage

Adds an image file to the output. This file will be copied over to a images folder in the output directory. To use this image in your script, simply use it the same as you would in standard markup, but refer to the image in the images directory.

Parameters

Required Type Description
Yes String The path to the file, relative to where the script is being run

Returns

Returns FruitJS object after adding script to allow chainability.

Examples

docs.addImage('myLogo.png');

In Markdown, you can place this image now using

![My Companies Name](images/myLogo.png)

addJS

Adds a JS file to the output. This file will be copied over to a js folder in the output directory and will be included on every page.

Parameters

Required Type Description
Yes String The path to the file, relative to where the script is being run

Returns

Returns FruitJS object after adding script to allow chainability.

Examples

docs.addJS('myStyles.css');

addLESS

Compiles a LESS file and adds it to the list of CSS for each page to use. This file will be copied over to a css folder in the output directory. Note: The name for this file will have the same name as the LESS file, except it will change the extension to .css if it is not already. This means you should note try to include a LESS file and CSS file that have the same name.

Parameters

Required Type Description
Yes String The path to the file, relative to where the script is being run

Returns

Returns FruitJS object after adding script to allow chainability.

Examples

docs.addLESS('myLESSStyles.less');

addPage

Adds a markdown page. This page will be added to automatic page menu building, and headings in this file will be parsed into submenu entries. The optional last parameter is used for marking a page as the homepage. If more than 1 page is marked as the homepage, the last one marked will become the homepage. If no homepage is provided, the first page added will be used. The order in the menu will be the order that the pages are added in.

Parameters

Required Type Description
Yes String The path to the file, relative to where the script is being run
Yes String The title of the page. This will be used when building the menu, and in the window title
No Boolean TRUE if this page should be used as the homepage, FALSE otherwise. Defaults to FALSE

Returns

Returns FruitJS object after adding script to allow chainability.

Examples

docs.addPage('intro.md', 'Getting Started', true)
    .addPage('section1.md', 'REST API');

buildMenu

This will use all current pages, and build an automatic menu from them. This will parse through each page to determine the header levels, and build submenus based on the headers of each page. This will override any previously created menus.

Submenus will be created based on the heading level of the current and the previous heading. That is to say, if the current heading is an h3, and the last heading was an h2, we will put the h3 heading as a submenu under the h2 heading.

Note: This process is asynchronous. A promise is returned that will resolve when the menu has finished being created. Rendering should be done after this is complete.

Parameters

Required Type Description
No Integer The level of headings to include in a submenu. For example, a value of 2 will include h1 and h2 tags, but will not include h3 or above in the menu generation

Returns

A Promise object. Promise will be resolved upon completion of the task, or rejected if we encounter an error.

Examples

docs.buildMenu(3)
    .then( function () {
        console.log('Menu was created');
    });

render

This compiles all of the markdown, and writes the files to a folder output in the directory where the script is being run.

Note: This process is asynchronous. A promise is returned that will resolve when the markdown has finished being written out.

Parameters

Required Type Description
NONE

Returns

A Promise object. Promise will be resolved upon completion of the task, or rejected if we encounter an error.

Examples

docs.render()
    .then( function () {
        console.log('Our documentation has come into existence!');
    });

setImageTitle

Allows you to set a specific image that has been added to be displayed as a logo in the navigation area (with the default theme). This image will be used instead of your title on the main page (though the original title set will still be used on for the window title). The alt text will be your original title text as well.

Parameters

Required Type Description
Yes String Name of the image that was added previous to use as a logo

Returns

Returns FruitJS object after adding script to allow chainability.

Examples

docs.addImage('folder/myLogo.png')
    .setImageTitle('myLogo.png');