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 into this interactive webpage.
Features:
Available themes:
dark (dark.html)light (light.html)yeolde (yeolde.html)clown (clown.html)sphinx (sphinx.html)Once the article.md article.md 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:
> 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
<div id="fig-code-fragment"> A Code Fragment
<pre>Hello World</pre>
</div>
A PHOTO
a photo
<div id='fig-photo'>
<img src='http://boscoh.github.io/supplescroll/photo.jpg'>
</div>
A VIDEO
a video
<div id='fig-youtube'>
Link to youtube
<br><br>
<iframe width="560" height="315" src="http://www.youtube.com/embed/Fk5reVYChlo?list=FLnRk0rt9QwA9a_mmCvlfXDw&start=52" frameborder="0" allowfullscreen></iframe>
</div>
article.html - ingredients of an HTML page that talks to supplescroll.
<html>
<head>
<title>My Article in Window</title>
</head>
<body>
<div id="banner">
<a href="http://github.com/boscoh/supplescroll">
supplescroll
</a>
> My Article
</div>
<h1>My Article with Supplescroll</h1>
<h2>A sub-heading</h2>
This is example code
<h3>Figure links</h3>
<p>I will talk about code
<a href="#fig-code-fragment"></a>,
a photo <a href="#fig-photo"></a>,
and a video <a href="#fig-youtube"></a>.
<h3>Reference links</h3>
With some links with references
(to <a href="#ref-1">this<a>),
to (<a href="#ref-2">that<a>),
and to (<a href="#ref-3">this one<a>).
<div id="fig-code-fragment">
A Code Fragment
<pre>Hello World</pre>
</div>
<div id="fig-photo">
<img src="http://boscoh.github.io/supplescroll/photo.jpg"/>
</div>
<div id="fig-youtube">
Link to youtube<br/><br/>
<iframe
allowfullscreen=""
frameborder="0"
height="315"
src="http://www.youtube.com/embed/Fk5reVYChlo?list=FLnRk0rt9QwA9a_mmCvlfXDw&start=52"
width="560">
</iframe>
</div>
<div id="fig-references">
REFERENCES
<br>
<br>
<div>
<a id="ref-1"></a>
<a href="http://google.com">http://google.com</a>
- a link to this well-known search engine.
</div>
<br>
<div>
<a id="ref-2"></a>
<a href="http://github.com">http://github.com</a>
- where the source-code is stored.
</div>
<br>
<div>
<a id="ref-3"></a>
<a href="http://boscoh.com">http://boscoh.com</a>
- the website of the author of this package.
</div>
<br>
</div>
</body>
</html>
You should:
> npm install -g supplescroll
You can browse the code at
http://github.com/boscoh/supplescroll
Pull-request new themes please.
supplescroll uses a typical YAML/markdown format to convert your documents into HTML. An example is in article.md:
The format consists of a:
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.
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
To create a figure, you must escape markdown with a <div> tag, and give the <div> an appropriate id="fig*".
The plain text after the <div> tag serves as a figure label, and this can be differentiated by latter text that is wrapped in <pre> or <code> 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.
Code Blocks. This is to make large blocks of code that the reader might want to look at with the main text. Use <pre> for a multi-line block, and <code> for inline references. These will be wrapped in a scrollable style. Make sure you escape HTML tags. Here's an example:
<div id='fig-code'>
Code Fragment Label
<pre>
Hello World
<escaped tag&rt; </pre>
</div>
which renders as Code Fragment.
Hello World <escaped tag>
Images. To insert photos with a label, you can add a label as text before the <img> tag in the figure:
<div id='fig-photo'>
Photo Label <br>
<img src='./photo.jpg'>
</div>
which gives Photo Insert.
Youtube Embeds. Text before the <img> tag works as a figure label. supplescroll knows how to resize embeds properly:
<div id='fig-youtube'>
Label to Youtube Video
<br><br>
<iframe width="560" height="315" src="//www.youtube.com/embed/Fk5reVYChlo?list=FLnRk0rt9QwA9a_mmCvlfXDw&start=52" frameborder="0" allowfullscreen></iframe>
</div>
which renders as Youtube Embedding.
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:
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). And make sure you fill in your preferred text.
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 <div> for a figure, which is illustrated with this code snippet .
Note the references are <a id="ref*"></a> tags that are wrapped by a <div>. This allows the correct placement of the reference back-link at the beginning of the <div>.
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:
<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>
Of course, you can just write the html yourself as in article.html article.html, and then run:
> supplescroll article.html light
which will insert references to the files:
supplescroll.css - basic styles for the page layoutlight.css - specific stylingssupplescroll.min.js - the javascript module that transforms the pageTo ensure supplescroll processes the correct items, in your HTML file, you should:
(optionally) include the banner through a top level <div id="banner">.
use <h*> tags for headers, which will all be incorporated into the table-of-contents.
name figures with <div id="fig*">.
name links to figures as <a href="fig*"> and name links to references as <a href="ref*">.
create a figure just to hold references <div id="fig-references">
put references in the fig-references as
<div>
<a id="ref-1"></a> My reference
</div>
(optionally) suppress figure/reference renmaing naming by adding
<script> window.is_rename = false </script>
If you are familiar with CSS then you can simply change the CSS in any of the themes, and rename the CSS, ensuring the link in the HTML file is also changed. Then send me the CSS!
2.1 (30/11/2015)
2.0 (16/11/2015)