Auto-generated Navigation

v.0.5.6

Navigation blocks in SourceJS are automatically generated on client-side, replacing a defined HTML hook with hand-crafted configuration.

Embedding

Copy and modify this HTML snippet to set-up your custom navigation.

<div class="source_catalog" data-nav="/docs"></div>

data-nav attribute defines the catalogue to be displayed. Inserting mentioned code in any SourceJS page a navigation like this will be generated:

Absolute paths

We recommend using absolute paths as most stable and predictable.

<div class="source_catalog" data-nav="/docs/api"></div>

Renders this navigation block:

Relative paths

Relative paths are also supported. During hook initialization, engine will replace ./ with current navigation URL.

<div class="source_catalog" data-nav="./api"></div>

Putting this HTML snippet in localhost:8080/docs page, it will be resolved to /docs/api/ catalog, same as with absolute path.

This feature is especially useful for nested catalogs and stand-alone collections like example-specs-showcase.

Headings and description automatic output

Auto-generated title and description in navigation block are taked directly from info.json meta file.

<div class="source_catalog" data-nav="./example"></div>

If there is no description, or you want to leave custom text, just use this extra markup:

<div class="source_catalog" data-nav="./example"> <h2>Custom Title</h2> <p>Custom description for catalogue.<p> </div>

Custom Title

Custom description for catalogue.

Filtering by tag

As it's possible to define different tags for specs in info.json files), they can be used for filtering custom navigation collection.

<div class="source_catalog" data-nav="/docs" data-tag="templates"></div>

Specs with "templates" tag

To call all specs without a tags, you can filter by "without-tag" string. Multiple tags filtering is also supported - templates, navigation.

Customizing Templates

Navigation markup is created from templates. You can extend this templates using options.js and Lodash templates syntax:

module.exports = { core: { ... }, assets: { ... moduleOptions: { globalNav: { templates: { catalogHeader: _.template('<h2 class="custom-class"><%= catalogMeta.title %></h2>'), } } } } }