Main Engine Documentation

v.0.5.6

This page contains main information about SourceJS engine and it's set-up.

SourceJS documentation is rendered by the engine itself and is shipped together with each instance.

Install

Before you start, please make sure that Git and Node.js are already installed on your system. Then install these NMP packages:

npm install -g yo generator-sourcejs

Having all dependencies in-place you will get a special yo sourcejs generator available for new instance initialization:

mkdir sourcejs && cd sourcejs yo sourcejs

To set-up a new engine instance chose the first option Init SourceJS in this folder. Generator also helps to bootstrap new Spec pages or plugins.

From NPM

npm version

To install SourceJS as a NPM package, first clone clean user configuration folder and then execute npm install.

git clone https://github.com/sourcejs/init.git -b npm my-sourcejs && cd my-sourcejs npm install sourcejs --save npm start

Starting from 0.6.0 we're planning to change official install path to one with NPM packages. Yeoman generator will be also replaced by sourcejs-cli with commands like run, install (plugin), init, create.

Installing On Windows

If you're running Windows and have some issues with JSDom dependencies compilation, please check this topic.

Alternatively with 0.5.6 we prepared a special build without JSDom, until it's full removal from core at 0.6.0.

npm install -g yo generator-sourcejs mkdir sourcejs && cd sourcejs yo sourcejs --branch 0.5.6-no-jsdom

Please note that Clarify feature is not available in no-jsdom version. If you had generator installed before, run npm update -g generator-sourcejs (v.0.4.2+ required).

And installing same build from NPM:

git clone https://github.com/sourcejs/init.git -b npm my-sourcejs && cd my-sourcejs npm install sourcejs@0.5.6-no-jsdom --save npm start

Commands

Run

Installation wizard will offer to start SourceJS right after initialization. To run it manually, trigger this command in newly created folder with SourceJS app:

npm start

To set an alternative server port, pass -- -p 8081 option.

Other configuration arguments are described in the help section:

npm start -- -h

Build

During the initial set-up, generator will build everything for you. To re-build the engine, run this command:

npm run build

It will trigger npm i and default build task for updating dependencies and building SourceJS assets. See the full list of all build tasks available.

Update

For updating SourceJS to a newer version, just pull the latest changes and trigger build:

git pull && npm run build

Creating First Spec

Specs are the main content files in SourceJS engine, in them you define all your component description and UI code for rendered examples. Originally we use *.src.html and *.md file templates with custom flavoured syntax. It is also possible to configure other technologies for writing Specs using plugins like Jade.

We treat Spec files as an interface, you can construct Spec page in many ways following only few simple rules. Each Spec folder must contain info.json with it's meta information and SourceJS compliant markup file. As an essential markup, engine requires only few hooks like .source_section, .source_example to define content sections and the rest is plain semantic HTML.

Spec Starting Template

After initialization, you get sourcejs/user folder, which is the place for all your custom content. All new Specs and configuration of main engine must be done there.

The starting template for new Spec pages can be found in sourcejs/docs/starting folder. Copy the contents to a new folder in source/user/specs and you'll be ready to write a new spec.

Check the SourceJS Spec page documentation.

Server-side Templating Engines

As we mentioned before, it's easy to use other server-side templating engines like Jade, you only need to create a simple SourceJS middleware (example) or process your sources with Grunt/Gulp.

By default all files are pre-processed with EJS, so you're free to use custom EJS features in any spec page - like includes or even plain JavaScript:

<%- include('filename.html') %> <% if (info.title === 'Title') {% > Action! <% } %>

Read more about Spec page generation helpers.

Client-side Templating Engines

For client-side templating you don't need any magic, just link Mustache or any other JS library to your page and use it whenever you want.

Remember, SourceJS Specs are a simple static pages, that are then enchanted with client-side scripts and internal APIs.

Examples

Main project website is based on SourceJS platform, as well as all documentation that you're surfing right now. Engine docs are both viewable on GitHub and in SourceJS environment.

Inspect Sourcejs.com source code to get better understanding of the basic source/user folder contents with engine configuration.

Bootstrap Bundle

To show you how SourceJS based documentation pages could be configured, we prepared a Bootstrap demo bundle. It represents a recommended way of structuring UI components, keeping all module related technologies in one place.

We highly encourage you setting up Bootstrap bundle on your SourceJS instance, and use it for experimenting and demoing documentation pages. Pull Requests are very welcome, adding more examples to this bundle, you will help yourself and other users getting more insights on how SourceJS specs could be organized.

Read our how-to articles, to get more information about the SourceJS catalog set-up.

Specs Showcase

Highlighting the variety of different ways for organizing Spec pages we gathered another special bundle. View it's source code at showcase repo and compare with rendered result.

Showcase includes both native Specs examples, and ones that are rendered with plugins like sourcejs-contrib-dss and sourcejs-jade.

Also check the SourceJS Spec page documentation.

Style Guide Driven Development

To get more insights about recommended workflow within Style Guide platform check this example bundle together with short screencast.

Configuration

SourceJS engine is highly configurable and allows to override almost any options from your instance set-up using personal configuration file sourcejs/user/options.js. All default, and safe to change options are described in base configuration file sourcejs/options.js.

With version 0.5.3 we also introduced context level options sourcejs-options.js, which allows to configure any catalog specifically for your needs. Read more about it, and other configuration capabilities in Engine Configuration doc.

Plugins

As a Style Guide Platform we focus on flexibility and ease of integration. All SourceJS core modules are easy to configure and replace with your customized version.

Plugins are working in the same way as core modules, but are kept outside the main platform, allowing to separate specific features.

Here is a list of available plugins:

These modules are able to extend both front-end and back-end part of the engine. To install any of official plugin, just use npm install in your sourcejs/user folder (note that some of them needs additional dependencies like MongoDB or CouchDB).

Follow this guide to learn how to develop own plugins for SourceJS Platform.

Contact us

Leave your questions and feedback as issues on GitHub orr request a consultation from SourceJS founders.

If you have any quick questions, or want to share your experience working with SourceJS, drop us a message in Gitter chat:

Gitter chat