--- title: supplescroll documentation banner: supplescroll documentation is_rename: True --- # SUPPLESCROLL _scrolling articles to your heart's delight_ > Supplescroll is a javascript plugin that converts a plain HTML document into an interactive document with auto-generated table-of-contents and easy-to-read figures and references. It turns this [markdown](https://raw.githubusercontent.com/boscoh/supplescroll/gh-pages/index.md) into this [interactive webpage](http://boscoh.github.com/supplescroll). Features: - auto-generated table of contents - independent figure list - handy URL hashes - back links to references - context-aware auto-scrolling - movable dividers - iOS-aware/responsive themes Available themes: - `dark` ([index.html](index.html)) - `light` ([light.html](light.html)) - `yeolde` ([yeolde.html](yeolde.html)) - `clown` ([clown.html](clown.html)) - `sphinx` ([sphinx.html](sphinx.html)) ## Usage Once the `article.md` [article.md](#fig-markdown) is written, then: > supplescroll article.md Which makes `article.html`. Open it. To choose another theme with your choice of output: > supplescroll -o colorful.html article.md clown With a plain HTML file `article.html` [article.html](#fig-html): > supplescroll article.html Which will overwrite `article.html` and copy the required files over to that directory.
article.md
- example of an article in supplescroll
```
---
TITLE: MY ARTICLE IN WINDOW TITLE
BANNER: MY ARTICLE HEADING IN PAGE
IS_RENAME: FALSE
---
THIS IS MY ARTICLE IN MARKDOWN
I will talk about the following things
CODE FRAGMENT
A code fragment
Hello World
article.html
- ingredients of an HTML page that talks to supplescroll.
```
I will talk about code , a photo , and a video .
Hello World
` or `` tags.
It is important to note that if you want to display HTML-code, you need to escape special HTML characters (`<`, `&`). You can do this wiht an [HTML-escape sanitizer](http://www.freeformatter.com/html-escape.html).
_Code Blocks_. This is to make large blocks of code that the reader might want to look at with the main text. Use `` for a multi-line block, and `` for inline references. These will be wrapped in a scrollable style. Make sure you escape HTML tags. Here's an example:
Code Fragment Label
Hello World
<escaped tag&rt;
which renders as [Code Fragment](#fig-code).
Code Fragment
Hello World
<escaped tag>
_Images_. To insert photos with a label, you can add a label as text before the `
` tag in the figure:
Photo Label
which gives [Photo Insert](#fig-photo).
Photo Insert
_Youtube Embeds_. Text before the `
` tag works as a figure label. `supplescroll` knows how to resize embeds properly:
Label to Youtube Video
which renders as [Youtube Embedding](#fig-youtube).
Youtube Embedding
### Figure links
In the main text, links to figures are identified as relative links to `#fig*`. To link to the above few figures, we can type:
- link to code [](#fig-code),
- link to photo [](#fig-photo),
- link to youtube [](#fig-youtube).
which will generate:
- link to code [](#fig-code),
- link to photo [](#fig-photo),
- link to youtube [](#fig-youtube).
### Automatic Figure Naming
By default, `supplescroll` will assign a label to all figures `(Figure 1)` etc. and references `[1]` etc. To turn this off, set `is_rename: false` field in the header ([example](#fig-markdown)). And make sure you fill in your preferred text.
### References
References are similar to figures, in that you can push references into the third column, and back-links are generated. As such you list all your references in a `` for a figure, which is illustrated with this code snippet [](#fig-reference-code).
Note the references are `` tags that are wrapped by a ``. This allows the correct placement of the reference back-link at the beginning of the ``.
In the main text, links to a reference are written:
Thus some text can be liberally sprinkled with a reference to:
- google [](#ref-1)
- github [](#ref-2)
- boscoh [](#ref-3)
Thus some text can be liberally sprinkled with a reference to:
- google [](#ref-1)
- github [](#ref-2)
- boscoh [](#ref-3)
example code for references
<div id="fig-references">
<h1>References</h1>
<div class="reference">
<a id="ref-1"></a>This is the detail to the linked reference, maybe it's a link<a href="http://boscoh.com">boscoh.com</a>
</div>
<div class="reference">
<a id="ref-2"></a>This is the detail to the linked reference, maybe it's a link<a href="http://boscoh.com">boscoh.com</a>
</div>
<div class="reference">
<a id="ref-3"></a>This is the detail to the linked reference, maybe it's a link<a href="http://boscoh.com">boscoh.com</a>
</div>
</div>
REFERENCES
http://google.com - a link to this well-known search engine.
http://github.com - where the source-code is stored.
http://boscoh.com - the website of the author of this package.
## Write Article in HTML
Of course, you can just write the html yourself as in `article.html` [article.html](#fig-html), and then run:
> supplescroll article.html light
which will insert references to the files:
- `supplescroll.css` - basic styles for the page layout
- `light.css` - specific stylings
- `supplescroll.min.js` - the javascript module that transforms the page
To ensure `supplescroll` processes the correct items, in your HTML file, you should:
1. (optionally) include the banner through a top level `