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.

FruitJS (pronounced Fruit Juice) is a documentation generator built in NodeJS. 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.

Features

Usage

You can 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 -g

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.

Contributing

FruitJS is available under the MIT license for anyone to use as they please. If you'd like to help out, feel free to fork us, and check out our issues for current tasks and planned features.

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.

Use

fruitjs <Manifest File> <Options>

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

-disableExtraction or -x

Flag to disable the automated extraction of files, images and links to include all referenced local files into the export

Format

-s

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 or folders 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 or folders 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 or folders you'd like to include on your pages. All of the JS files will be added to each page.
images Array [] An array of extra image files or folders you'd like to include in your export. Files will be put in the images folder, and can be referred to in your markdown from that folder
assets Array [] An array of extra files or folders you'd like to include in your export. 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
preMenu Array or Object null Menu items you'd like to add before the generated menu
postMenu Array or Object null Menu items you'd like to add after the generated menu

Additional Menu Items

Sometimes you want to add additional menu items for navigation to other locations, files, or examples. You can do this through the preMenu and postMenu options in the manifest. These can be either a single object, or an array of objects of the format below.

{
    "Name" : <STRING> Display name of link
    "URL" : <STRING> URL to link to (Optional)
    "SubMenu" : <ARRAY> Array of SubMenu items (Optional)
}

Unless disabled, links and images referenced in your markdown pages is automatically gathered up and placed in the appropriate folder. You can use the images and assets properties in the manifest file to add any additional items you'd like to include in your exported folder, but are not referenced in your pages.

Code API

FruitJS Constructor

new FruitJS ( Title[, OutputDir[, RelativeLocation]] )

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

Parameters

Name Required Type Description
Title Yes String The title of the documentation. This will be used as the title in the browser window and on the page.
OutputDir No String Directory to output to. Relative to current running directory. Default is output
RelativeLocation No String Relative location from which to pull files. Default is current working directory

Returns

New FruitJS object

Examples

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

addAsset

.addAsset( FilePath )

Adds a file to the output. This file will be copied over to an asset folder in the output directory.

Parameters

Name Required Type Description
FilePath Yes String The path to the file, relative to RelativeLocation

Returns

Returns FruitJS object after adding script to allow chainability.

Examples

docs.addCSS('myStyles.css');

addCSS

.addCSS( FilePath )

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

Name Required Type Description
FilePath Yes String The path to the file, relative to RelativeLocation

Returns

Returns FruitJS object after adding script to allow chainability.

Examples

docs.addCSS('myStyles.css');

addImage

.addImage( FilePath )

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

Name Required Type Description
FilePath Yes String The path to the file, relative to RelativeLocation

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

.addJS( FilePath )

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

Name Required Type Description
FilePath Yes String The path to the file, relative to RelativeLocation

Returns

Returns FruitJS object after adding script to allow chainability.

Examples

docs.addJS('myStyles.css');

addLESS

.addLESS( FilePath )

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

Name Required Type Description
FilePath Yes String The path to the file, relative to RelativeLocation

Returns

Returns FruitJS object after adding script to allow chainability.

Examples

docs.addLESS('myLESSStyles.less');

addPage

.addPage( FilePath, Title[, IsHomepage] )

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

Name Required Type Description
FilePath Yes String The path to the file, relative to RelativeLocation
Title Yes String The title of the page. This will be used when building the menu, and in the window title
IsHomepage No Boolean TRUE if this page should be used as the homepage. 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');