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 = ; ;
With Options
var scrollRack = ; // Full options list with defaults
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