Scroll Rack

A small collection of Metalsmith plugins and custom modules intended to generate guidlines and documentation for your company, in form of a static web page. It is ready for use and requires almost not configuration or other setup. Just require it and specify a source and destination directory.

Features:

• Parse Markdown files with markdown-it
• Enabled footnotes via markdown-it-footnote
• Code highlighting with highlight.js
• Genernate table of contents & navigation
• Provide local server + livereload (for development and writing)

Installation

$ npm install --save scroll-rack

How Stuff gets parsed

Scroll Rack will read all contents inside a directory, specified via the files option. The structore of the contents will be persisted. A navigation is automatically generated based on the folder structure. Sub-directories will be treated as content sections and every Markdown file will be parsed to HTML and made availble as a child page of its section. All generated content is put inside a dest.

Example:

If you specified docs as your root and have the following folder structure:

docs/
 ├── javascript/
 │     ├── types.md
 │     ├── references.md
 │     ├── arrays.md
 │     └── objects.md
 │
 └── coding_styleguide/
       ├── modules.md
       ├── services.md
       └── testing.md

The generated navigation/table of contents will look like this (where the displayed name of page is its title attribute):

1. JavaScrip
  1.1 Types
  1.2 References
  1.3 Arrays
  1.4 Objects

2. Coding Styleguide
  2.1 Modules
  2.2 Services
  2.3 Testing

Metalsmith allows the usage of YAML front-matters. A title is required and will not be read from the Markdown.

Usage

Simple

var scrollRack = require('scroll-rack');
 
scrollRack({
    files: 'docs',
    dest: '__build'
});

With Options

var scrollRack = require('scroll-rack');
 
// Full options list with defaults
scrollRack({
 
  // Required
  files: undefined,                       // Documentation files root dir
  dest: undefined,                        // Destination for generated files
 
  // Optional
  assets: undefined,                      // Assets folder, copied to /assets
 
  ignore: ['*.js', '*.ts', '.DS_Store'],  // Patterns that should not be copied to dest,
                                          // will be used in "metalsmith.ignore"
 
  redirect: true,                         // Create redirects to prevent navigation
                                          // to "empty pages", redirect to first
                                          // available page in a section instead
 
  code_theme: 'atelier-forest.light',     // See https://highlightjs.org/static/demo/
                                          // for a full list of available themes
  nav: {
    order: [],                            // Custom ordering of content sections,
                                          // default is alphabetically
 
    sort: function                        // Custom sorting function for sub-sections,
                                          // will user "oder" if specified
  },
 
  port: 8080,                             // Port for local server
 
  callback: undefined                     // Function which is called when build finished
                                          // Is only executed w/o --serve flag
});

Asset links

Sometimes using the correct path to an asset can be frustrating, esspecially if you have to specify a relative path because you host the generate files in a sub-directory or something similar. Scroll Rack supports you by automatically parsing all assets paths to relative paths.

For example: Writing ![Image](/assets/my-image.png) in a file named section/some-page.md would be parsed to ../../assets/my-image.png because the file will get the following permalink section/some-page/index.html.

Page in Root Directory

You can position page before or after the section list inside the navigation by setting the nav_position property in the front matter to before/after. By default pages are added before the section list.

Local Server with Livereload

Running your script with --serve will start the local server with livereload.

Backlog

• Parse source code to generate additional documentation via @ comments
• Documentation for TypeScript Interfaces
• Documentation for custom HTML/Web Components and their API

Release History

• 0.5.5 Styling for img
• 0.5.4 Styling for h4
• 0.5.3 Fix error with not loading main.js and livereload instead ...
• 0.5.2 Fix navigation of before/after pages. See f996f78573b6b98c476a6b28bb6fb739fbfdd0d7
• 0.5.1 Add callback option.
• 0.5.0 Create navigation for pages in root, position it before/after sections.
• 0.4.6 Minor typography improvements for paragraphs and block quotes.
• 0.4.5 Style foot notes and code blocks.
• 0.4.4 Improve typography.
• 0.4.3 Remove deprecated dependency.
• 0.4.2 Make header anchors more accessible.
• 0.4.1 Improved typography.
• 0.4.0 Add markdown-it-smartarrows and markdown-it-anchor (#1)
• 0.3.0 Make linking to assets easier (#2)
• 0.2.0 Add option to specify an assets folder
• 0.1.0 Initial release