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