This is the documentation home for authors writing content on this site. It covers everything you need to create posts — from plain Markdown articles to interactive visual essays with zoomable images, maps, video, and text-driven interactions.
New here? Start with the Authors Guide — it walks you through creating, previewing, and publishing your first post entirely from GitHub’s web interface. If you are brand new to GitHub and Markdown as well, the Authoring a Visual Narrative tutorial assumes no prior experience at all and takes you from creating a GitHub account to publishing a first essay.
The guides are organized in the order most authors need them:
| Guide | What it covers |
|---|---|
| Authoring a Visual Narrative | A start-to-finish tutorial for first-time authors — no GitHub, Jekyll, or Markdown experience assumed |
| StoryKit Overview | What StoryKit is, what it adds, and how it is enabled |
| Authors Guide | Creating, previewing, and publishing a post step by step |
| Preview Setup | One-time setup for the fast live-preview tool |
| Formatting Tips | Controlling viewer size, position, and text wrapping |
The StoryKit Editor (beta) is a browser-based Markdown editor for StoryKit posts: live preview, viewer-tag autocomplete, drag-and-drop media, and GitHub sync — a one-window alternative to the GitHub web editor + preview tool workflow. One central editor serves every StoryKit repo: save a GitHub token once and open, edit, and commit files in any repository you can write to.
Viewers are the interactive elements you add to a post with a simple include tag. The Viewers Overview lists them all at a glance; each then has its own reference page:
| Guide | Viewer |
|---|---|
| Image Viewer | Zoomable, pannable high-resolution images (incl. Wikimedia Commons and IIIF) |
| Map Viewer | Interactive maps with markers, overlays, and fly-to actions |
| Image Compare Viewer | Before/after image slider with alignment tools |
| YouTube Viewer | Clean video previews with timed playback actions |
| Network Viewer | Node-and-edge relationship diagrams from simple CSV data |
| Iframe Viewer | Embed any external web page or widget |
| Entity Info Popups | Contextual popups powered by Wikidata |
| Guide | What it covers |
|---|---|
| Action Links | The complete reference for making text trigger viewer actions |
| Display Modes | Flat pages vs. the two-column scrollytelling layout |
The Troubleshooting Guide covers the most common problems — a viewer that shows nothing, an action link that does nothing, images that don’t update — and how to fix them.
Most content authors do not need to understand HTML, CSS, or JavaScript.
If you are comfortable writing basic Markdown and copying small snippets of example code, you have all the technical background required. The examples in these guides are meant to be copied directly into your own posts and adapted.
This site is built on the Chirpy Jekyll theme. Chirpy provides the publishing engine — layouts, navigation, typography, tags, and categories — and StoryKit adds the interactive storytelling layer on top. For theme-level topics not covered here (site configuration, favicons, advanced typography), see the official Chirpy documentation.
A start-to-finish guide for students creating their first interactive visual narrative on a StoryKit site. Covers what StoryKit is and where it came from, the GitHub workflow you'll use to draft and publish, the Markdown you'll write, and every StoryKit viewer the platform offers.
An introduction to StoryKit — a Markdown-first framework for adding interactive viewers and text-driven media interactions to a Jekyll + Chirpy site. This overview explains StoryKit origins, how it fits into the existing architecture, and how it is enabled and configured for individual posts.
A practical guide for writing, previewing, and publishing StoryKit posts entirely through GitHub’s web interface. It explains how GitHub rebuilds sites after commits, how the live preview tool bypasses that delay for rapid iteration, and how to correctly structure front matter, media folders, and asset references.
A guide for configuring the StoryKit Preview Tool. The tool uses a bookmarklet and GitHub token, enabling one-click live preview of any post directly from GitHub's file browser.
Tips for formatting StoryKit posts.
A one-page tour of every StoryKit viewer — what each one does, when to use it, and where to find its full reference guide.
How to use the StoryKit image viewer in your Markdown posts.
How to use the StoryKit map viewer in your Markdown posts.
How to use the StoryKit Image Compare viewer in your Markdown posts.
How to use the StoryKit YouTube viewer in your Markdown posts.
How to use the StoryKit network viewer to draw node-and-edge relationship diagrams from simple CSV data in your Markdown posts.
How to embed external web pages, exhibits, and widgets in your Markdown posts with the StoryKit iframe viewer.
How to create rich information popups using Wikidata entities in StoryKit.
The complete reference for action links — the Markdown links that let your text zoom images, fly maps, and play video segments.
How StoryKit posts can be presented — as a traditional flat page or as a two-column scrollytelling layout — and how to choose and configure each mode.
Fixes for the most common problems authors hit — blank viewers, action links that do nothing, images that won't update, and popups that never load.