literasee-viewer

Open source bl.ocks.org clone, with a sprinkling of custom features.

The literasee viewer is deployed to http://literasee.org/, where it can be used to display work that has been published as a Gist. To view a GitHub user's eligible Gists simply add their username to the end of the URL. For example, http://literasee.org/bclinkinbeard/ will display a grid of Gists by bclinkinbeard. The page will only list Gists that can be displayed by the viewer, which is determined by the criteria described below.

To display a Gist, you can select it from the user dashboard or enter the URL directly. The URL format for Gists just appends the Gist id to the end of the user URL, so http://literasee.org/bclinkinbeard/bdba0145af07d5afeb92/ would display the Gist created by bclinkinbeard whose id is bdba0145af07d5afeb92.

When a Gist is rendered, a small panel will be displayed in the top right corner which links to the Gist source code and the author's dashboard page.

Supported Gist Structure

In order to be displayed, a Gist must have at least one of the following files.

• index.html
• index.md
• slides.md
• tufte.md

If an index.html file is found, it will be served as-is when accessing the Gist's URL.

Markdown files will be converted to HTML before serving, using the marked library from npm.

If the Gist does not contain an index.html file, the Gist URL will default to serving index.md.

If the Gist has a slides.md file you can add /slides to the URL to have it served. slides.md will be rendered using the Reveal.js library.

If the Gist has a tufte.md file you can add /tufte to the URL to have it served. tufte.md will be rendered using the Tufte CSS project.

Scripts

Any .js files in your Gist will be included in the rendered page. The script tags will be placed just inside the closing body tag to avoid blocking any rendering, but the document is not guaranteed to be ready by the time your script runs. You are encouraged to check for a ready state in your script if necessary.

Styling

Any .css files in your Gist will also be included in the page, after the provided default CSS files. All CSS is specified in link tags in the head of the document.

index.md files will be rendered using YetiCSS, slides.md files will be rendered using Reveal.js themes, and tufte.md files will be rendered using Tufte CSS.

Thumbnails

You can add a thumbnail.png to your Gist and it will be used on your user dashboard as a preview of the Gist.

Markdown support

When rendering slides.md and tufte.md files, sections are delimited using a triple dash surrounding by blank lines. For example:

# Presentation Title
## Witty Subtitle

By: Some Author

---

## Slide Two Title

* Some
* List
* Items

slides.md files are rendered by Reveal.js, so any Markdown capabilities of that project should be supported in this viewer.

Per-slide scripts

When embedding visualizations or other interactive elements, it may be desirable to execute a function when a slide becomes active. To do so, define a function in one of the .js files in your Gist, and then list the function name to be called within your slide section. You may also include HTML fragments if necessary, in case you are using something like D3.js.

For example:

// app.js
function createBarChart () {
	// chart creation, etc.
}

# Presentation Title
## Witty Subtitle

By: Some Author

---

## Slide Two Title

<div id="chart"></div>

* Some
* List
* Items

Function: createBarChart

Local usage

The deployed app cannot access Gists or updates that have not been pushed to GitHub. To facilitate efficient development workflows, the viewer can be installed locally, where the only requirement for seeing the effects of code changes is saving the file and refreshing your browser.

Note: It is assumed you have already installed Node.js and npm. If this is not the case, go to http://nodejs.org and follow the installation instructions.

Run npm install -g literasee-viewer from the command line to globally install the viewer. Once the installation completes you can run the literasee-viewer from any directory on your machine.

Running literasee-viewer with no arguments will start a server on port 3000 that serves the files in the directory in which it was run.

Use the --dir flag (-d for short) to serve files from another directory.

Use the --port flag (-p for short) to run the server on a port other than 3000.

For example, literasee-viewer -d my-gist -p 8080 would serve the my-gist directory on port 8080.

You can also run literasee-viewer -h to get help with the supported commands.