Version: 0.5.3
SourceJS Living Style Guide Plaftorm is focused on two important workflows - Modular UI Development and Living Style Guide Driven Development. Support of multiple libraries combination for different projects or just a set of standalone Front-end modules is one of the key features engine provides.
To make things clear, let's first define some main keywords.
- Component - standalone instance in your catalogue, could be a UI module (a button, web component, Angular directive), text documentation page, or a small CSS framework
- Spec - a documentation page, which describes your component; in SourceJS is rendered out of
index.src.html,readme.md,index.jade, DSS doc or other custom formats you define - Catalog/Bundle - Is a set of components with Specs, that you put in to SourceJS
Most typical SourceJS set-up that I've configured for multiple teams looks like this:
/sourcejs (Git repo) - engine sources (don't need to modify)
/core
/assets
/docs
/user (Git repo) - SourceJS instance configuration and content repo
/core - overriding engine core
/assets - overriding engine assets
/specs - default catalog folder for Specs
/bootstrap (Git repo) - nested bundle with Bootstrap components
/bootstrap-component1
index.src.html - default template for describing component
info.json
/bootstrap-component2
...
index.src.html - default template for describing Nav page
info.json - essential Spec or Nav page config file
/project-bundle (Git repo) - nested project specific bundle
/component1 (Git repo) - nested standalone component
index.src.html
info.json
/component2 (Git repo)
README.md - alternative MD template for describing component
info.json
Following official engine setup instructions after running yo sourcejs setup process, you will get sourcejs folder with Git repo attached. It is safe to clean .git folder, but we suggest keeping this repo initialized for easy updates via git pull.
After set-up, apart from engine sources, you get personal configuration folder sourcejs/user. There you define custom options, override engine views and keep your documentation contents.
We suggest setting up personal version control repo in sourcejs/user folder, so you can share your setup with the rest of the team.
SourceJS supports multiple catalog system. It means you can create deep nesting level with different bundles inside. Default init script creates sourcejs/user/specs folder with first Spec example. You can rename specs folder, and use your own catalogs and freely nest other catalogs and sub-repos inside.
As mentioned in the basic setup file scheme above, it's recommended to keep UI component bundles in separate repos. Here are few example bundles used in sourcejs.com setup:
- https://github.com/sourcejs/example-bootstrap-bundle
- https://github.com/sourcejs/example-specs-showcase
The only main requirement for SourceJS compliant bundles and Specs is info.json file, where you keep meta information about documentation or navigation pages. Additionally to it, you will also need to provide README.md or index.src.html files to define Spec contents for the engine to render.
If you want to have a bundle level navigation like in Example Specs section, set-up a simple index.src.html template following generated nav doc.
<div class="source_subhead">
<h1>My custom bundle</h1>
</div>
<div class="source_catalog" data-nav="bundle-folder-name" data-tag="without-tag">
<h2 class="source_catalog_title">Bundle navigation title</h2>
</div>And create the info.json meta configuration file next to it.
{
"title": "My custom bundle",
"role": "navigation"
}Check example bundle root and compare it with rendered result.
To render a Spec page per component, and list it in navigation page, info.json file must be added to each item:
/bundle
/component1
component.css
component.js
index.template
info.json
readme.md
/component2
component.css
info.json
index.src.html
Check out index.src.html Spec example.
As you might notice, I also mention index.template file, which highlights that it's possible to define many different technologies for describing a spec page. Here's an official showcase bundles with examples of different spec technologies - sourcejs.com/specs/example-specs-showcase.
Feel free to store all component sources and documentation right in sourcejs/user folder. But if you want to re-use some of the components across different projects, it's better to organize each bundle in separate repo.
One of the easiest options to configure nested repos, is to use Git submodules. To define a submodule, run this command from parent repo in sourcejs/user:
git submodule add https://github.com/sourcejs/example-bootstrap-bundle.git specs/example-bootstrap-bundle
To update all existing submodules run:
git submodule foreach git pull origin master
This set-up helps keeping all catalogs in one place. Using git clone --recursive other team members will get the same sub-repo structure with all SourceJS contents.
Read more about Git Submodules in official specs.
If you prefer flat tree, instead of submodules use symlinks:
git clone https://github.com/sourcejs/example-bootstrap-bundle.git
ln -s example-bootstrap-bundle/ sourcejs/user/specs/example-bootstrap-bundle
With SourceJS 0.5.3 release, engine supports context options. Using sourcejs-options.js file in any catalog, all child spec pages will use the custom settings you provide.
Read more about context options in this how-to article.
If you have more questions feel free to reach us by email or just use our Gitter chat:
