--- 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
A Code Fragment
Hello World
A PHOTO a photo
A VIDEO a video
Link to youtube

```
article.html - ingredients of an HTML page that talks to supplescroll. ``` My Article in Window

My Article with Supplescroll

A sub-heading

This is example code

Figure links

I will talk about code , a photo , and a video .

Reference links

With some links with references (to this), to (that), and to (this one).
A Code Fragment
Hello World
Link to youtube

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.

```
## Installation You should: > npm install -g supplescroll You can browse the code at     Pull-request new themes please. ## Write Article with Markdown `supplescroll` uses a typical YAML/markdown format to convert your documents into HTML. An example is in [article.md](#fig-markdown): The format consists of a: 1. header in [YAML](http://www.keleshev.com/yaml-quick-intoduction) 2. body in [markdown](https://daringfireball.net/projects/markdown/basics) ### YAML header The `title` is the text that goes in the Window title. The `banner` string is inserted into the banner part of the page. The `is_rename` boolean indicates whether links to references and figures are to be renamed. ### Headers Write the text in markdown, making sure to use proper markdown headers, which will be used to construct the table of contents: # A Header ## A Secondary Header ### Figures To create a figure, you must escape markdown with a `
` tag, and give the `
` an appropriate `id="fig*"`. The plain text after the `
` tag serves as a figure label, and this can be differentiated by latter text that is wrapped in `
` 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 `