Shins development continues at
Note: development on Shins has stopped. Please see ReSlate for the replacement.
Beautiful static documentation for your API.
Shins is a port of Slate to Javascript / Nodejs, and would not be possible without all of that hard work.
Version numbers of Shins aim to track the version of Slate they are compatible with.
npm install
node shins.js
(alias npm run build
) or
node shins.js --minify
ornode shins.js --customcss
ornode shins.js --inline
ornode shins.js --unsafe
ornode shins.js --no-links
--logo
option with path to your logo image.source/layouts/layout.ejs
use the --layout
option.--logo-url
option with URL to link to../index.html
, use the --output
or -o
option.--attr
option.source
and pub
directories using the --root
option.node arapaho
or npm run serve
and browse to localhost:4567 - changes to your source .html.md
files and the source/includes
directory will automatically be picked up and re-rendered. If you use --launch
or -l
or npm run start
your default browser will be opened automatically. You can also pass shins
options on the arapaho
command-line.Or, to deploy to GitHub Pages:
https://{yourname}.github.io/{repository-name}
To deploy to your own web-server:
If you use the option --minify
to shins, the only things you need to take to your web host is the generated index.html
and the contents of the pub
directory, which should be kept relative to it, so the structure is always:
{whatever}/index.html
{whatever}/pub/css/
{whatever}/pub/js/
If you use the --inline
option to shins, then everything is bundled into the index.html
file and no pub
directory is required. Fonts are by default loaded from this github repository, but this can be overridden with the --fonturl
option.
A Dockerfile
is included. To build:
docker build . -t shins:latest
to run:
docker run -p 4567:4567 -v $(pwd)/source:/srv/shins/source shins:latest
There is a simple example of using an index markdown file as an entry point to a collection of Shins pages here.
const shins = require('shins');
let options = {};
options.cli = false; // if true, missing files will trigger an exit(1)
options.minify = false;
options.customCss = false;
options.inline = false;
options.unsafe = false; // setting to true turns off markdown sanitisation
options['no-links'] = false; // if true, do not automatically convert links in text to anchor tags
//options.source = filename; // used to resolve relative paths for included files
shins.render(markdownString, options, function(err, html) {
// ...
});
or, with Promises:
const shins = require('shins');
let options = {};
options.cli = false; // if true, missing files will trigger an exit(1)
options.minify = false;
options.customCss = false;
options.inline = false;
options.unsafe = false; // setting to true turns off markdown sanitisation
options['no-links'] = false; // if true, do not automatically convert links in text to anchor tags
//options.source = filename; // used to resolve relative paths for included files
options.logo = './my-custom-logo.png';
options['logo-url'] = 'https://www.example.com';
shins.render(markdownString, options)
.then(html => {
// ...
});
The err
parameter is the result of the ejs
rendering step.
Setting customCss
to true
will include the pub/css/screen_overrides.css
,pub/css/print_overrides.css
and pub/css/theme_override.css
files, in which you can override any of the default Slate theme, to save you from having to alter the main css files directly. This should make syncing up with future Shins / Slate releases easier.
Setting inline
to true
will inline all page resources (except resources referenced via CSS, such as fonts) to output html. This way HTML can be used stand-alone, without needing any other resources. It will also set minify
to true
.
Set logo
path to add your custom logo as absolute path or path relative to process working directory. If inline
option is on image will be inlined, else it will be copied to source/images
directory and included via src
image attribute.
Set logo-url
if you want the logo image to link to a webpage.
updateFromSlate
assumes you have Ruby Slate checked-out by the side of shins (i.e. in a sibling directory) and will copy .scss files, fonts, Javascript files etc.buildstyle.js
program can be used to process the .scss files to their .css equivalents. It takes one optional parameter, the outputStyle
used by node-sass
. This can be either nested
, expanded
, compact
or compressed
. Default is nested
. It also respects the --root
option.highlight_theme
in your slate markdown header)arapaho
has a --preserve
or -p
option which will not overwrite your .html
output file, but still re-render when necessarypub/css/tradegecko.min.css
can be included with the --css
optioninclude::filename[]
syntax as well as !INCLUDE filename
from markdown-pp - this is not supported by Slate. See some more information about including files.Please feel free to add a link to your API documentation here