# shins

> Shins Is Not Slate

Latest version **2.6.0** (published 2020-05-19) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install shins
pnpm add shins
yarn add shins
bun add shins
```

Provides the command `shins`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.6.0 |
| Published | 2020-05-19 |
| First published | 2016-10-05 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 16 |
| Unpacked size | 958.7 KB |
| Known vulnerabilities | 0 (+12 in 3 direct dependencies) |
| Install scripts | no |
| GitHub stars | 248 |
| Author | Mike Ralphson |
| Maintainers | mermade |
| Keywords | shins, slate, swagger, openapi, api, documentation, docs |

## Links

- npm: https://www.npmjs.com/package/shins
- Repository: https://github.com/Mermade/shins
- Homepage: https://github.com/Mermade/shins#readme
- Issues: https://github.com/Mermade/shins/issues
- npm.io page: https://npm.io/package/shins

## Dependencies (16)

- [ejs](https://npm.io/package/ejs.md) ^2.5.1
- [opn](https://npm.io/package/opn.md) ^5.2.0
- [yaml](https://npm.io/package/yaml.md) ^1.9.2
- [cheerio](https://npm.io/package/cheerio.md) ^1.0.0-rc.2
- [express](https://npm.io/package/express.md) ^4.15.5
- [chokidar](https://npm.io/package/chokidar.md) ^3.0.2
- [uglify-js](https://npm.io/package/uglify-js.md) ^2.7.4
- [compression](https://npm.io/package/compression.md) ^1.6.2
- [markdown-it](https://npm.io/package/markdown-it.md) ^10.0.0
- [highlight.js](https://npm.io/package/highlight.js.md) ^10.0.2
- [call-me-maybe](https://npm.io/package/call-me-maybe.md) ^1.0.1
- [sanitize-html](https://npm.io/package/sanitize-html.md) ^1.15.0
- [tiny-opts-parser](https://npm.io/package/tiny-opts-parser.md) 0.0.3
- [markdown-it-attrs](https://npm.io/package/markdown-it-attrs.md) ^1.2.1
- [markdown-it-emoji](https://npm.io/package/markdown-it-emoji.md) ^1.4.0
- [markdown-it-lazy-headers](https://npm.io/package/markdown-it-lazy-headers.md) ^0.1.3

## Alternatives

- [@cantoo/pdf-lib](https://npm.io/package/@cantoo/pdf-lib.md) — 297.9K weekly downloads
- [datatables.net-buttons](https://npm.io/package/datatables.net-buttons.md) — 200.1K weekly downloads
- [@ckeditor/ckeditor5-export-pdf](https://npm.io/package/@ckeditor/ckeditor5-export-pdf.md) — 167.0K weekly downloads
- [scanbot-web-sdk](https://npm.io/package/scanbot-web-sdk.md) — 15.0K weekly downloads
- [@syncfusion/ej2-angular-pdfviewer](https://npm.io/package/@syncfusion/ej2-angular-pdfviewer.md) — 8.8K weekly downloads

## Recent versions

- 2.6.0 (latest) — 2020-05-19
- 2.5.0 — 2020-05-11
- 2.4.1-0 — 2019-12-05
- 2.4.0 — 2019-11-13
- 2.3.2-6 — 2019-09-27
- 2.3.2-5 — 2019-08-12
- 2.3.2-4 — 2019-03-22
- 2.3.2-3 — 2018-11-30
- 2.3.2-2 — 2018-11-19
- 2.3.2-1 — 2018-09-21
- 2.3.2-0 — 2018-08-17
- 2.3.1 — 2018-07-06
- 2.2.1-6 — 2018-06-19
- 2.2.1-5 — 2018-05-10
- 2.2.1-4 — 2018-05-10
- … 23 more at https://npm.io/package/shins/versions

## README

# shins

### Shins Is Not Slate

Beautiful static documentation for your API.

![logo](https://github.com/Mermade/shins/blob/master/docs/logo.jpg?raw=true)

Shins is a port of [Slate](https://github.com/slatedocs/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.

![screenshot](https://github.com/Mermade/shins/blob/master/docs/screenshot.jpg?raw=true)

### Usage

* Fork the repository
* Clone the fork
* Edit source/index.html.md
* `npm install`
* `node shins.js` (alias `npm run build`) or
    * `node shins.js --minify` or
	* `node shins.js --customcss` or
	* `node shins.js --inline` or
    * `node shins.js --unsafe` or
    * `node shins.js --no-links`
* To add custom logo add `--logo` option with path to your logo image.
* To use a different layout template (default `source/layouts/layout.ejs` use the `--layout` option.
* To make the logo image link to a webpage, add `--logo-url` option with URL to link to.
* To specify a different output filename from the default `./index.html`, use the `--output` or `-o` option.
* To allow css-style attributes in markdown, specify the `--attr` option.
* You can specify another location for the `source` and `pub` directories using the `--root` option.
* To check locally: `node arapaho` or `npm run serve` and browse to [localhost:4567](http://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.
* Add, commit and push
* Then (in your fork) press this button

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)

Or, to deploy to GitHub Pages:

* Change the setting on your fork so Github Pages are served from the root directory
* Browse to `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.

### Docker

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`

### Multiple Shins pages / portal

There is a simple example of using an [index markdown file](./source/portal.html.md) as an entry point to a collection of Shins pages [here](https://mermade.github.io/shins/portal.html).

### API

```javascript
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:

```javascript
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.

### Updating from Slate

* Note: changes to Slate CSS, Javascript etc may break assumptions made in Shins. Use at your own risk.
* The script `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.
* The `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.

### Notes

* Windows is definitely supported
* Syntax highlighting in 189 [languages](https://highlightjs.org/static/demo/) and 91 [themes](https://highlightjs.org/static/demo/) (you can specify the highlighter theme to use by setting `highlight_theme` in your slate markdown header)
* Multiple language tabs per language are supported
* Static TOC as per Slate v2.0
* [GitHub emoji shortcuts](https://gist.github.com/rxaviers/7360908) are supported
* For converting [OpenAPI / Swagger](https://github.com/OAI/OpenAPI-Specification) or [AsyncAPI](https://github.com/asyncapi/asyncapi) definitions to Shins or Slate, see [widdershins](http://github.com/mermade/widdershins)
* `arapaho` has a `--preserve` or `-p` option which will not overwrite your `.html` output file, but still re-render when necessary
* Shins ships with an alternate theme by [TradeGecko](https://github.com/tradegecko) which is also under the Apache 2.0 license, `pub/css/tradegecko.min.css` can be included with the `--css` option
* Shins additionally supports [AsciiDoc](http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files) `include::filename[]` syntax as well as `!INCLUDE filename` from [markdown-pp](https://github.com/MikeRalphson/markdown-pp-js) - this is not supported by Slate. See some [more information about including files](/docs/include.md).

### Shins in the wild

Please feel free to add a link to your API documentation here

* [APIs.guru OpenAPI specification extensions (Semoasa) documentation](https://mermade.github.io/shins/apisguru.html)
* [Signal Biometrics Ox documentation](https://signalbiometrics.github.io/ox-docs/)
* [LeApp daemon API](https://leapp-to.github.io/shins/index.html)
* [Shutterstock API](https://api-reference.shutterstock.com/)
* [Shotstack Video Editing API](https://shotstack.io/docs/api/index.html)

---
_Source: https://npm.io/package/shins · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._