StoryKit Authoring Guide

(GitHub + StoryKit Editor Workflow)

This guide explains how to create, preview, and publish posts using GitHub’s web editor and the StoryKit Editor.

1. Open the StoryKit Editor

Use the StoryKit Editor for Markdown editing and live preview. Sign in with GitHub when you are ready to sync a repository. See the editor guide.

2. Creating a New Post

(Example: Monument Valley)

Go to _posts.

Open .template.md and copy the contents.

Create a new file using a filename formatted YYYY-MM-DD-<Post_Title>.md, for example”

1

2026-01-10-monument-valley.md

Paste the template contents into the newly created file and edit the front matter. When finished with updating the front matter, commit (save) the file.

3. Completing the Front Matter

Example based on the Monument Valley post:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

---
title: Monument Valley
description: Interactive visual essay on Monument Valley.
authors:
  - Ron Snyder
date: 2026-01-10
categories: [examples]
tags: [Monument Valley]
published: false
media_subpath: /assets/posts/monument-valley
image:
  path: Monument_Valley.jpg
  alt: Monument Valley
---

Key Points

  • published: false while drafting; change to true to publish
  • media_subpath must exactly match the folder name created in the /assets/posts folder
  • image.path uses filename only
  • A single author can also be given as author: Name; use the authors: list form for one or more authors
  • StoryKit is on by default — no front matter needed to use viewers or action links. Add storykit: false to opt a post out, or a storykit: settings block to fine-tune behavior (see the Display Modes guide)

4. Images and Assets (Monument Valley Example)

This is an optional step to be performed in locally hosted content (generally images) will be used in the post.

Step 1 — Create Folder

1

/assets/posts/monument-valley/

Upload any local images used in post:

1

Monument_Valley.jpg

Step 2 — Match media_subpath

1

media_subpath: /assets/posts/monument-valley

Exact spelling matters.

Step 3 — Reference Only Filenames

When media_subpath is set in the post front matter only filenames are used in image and StoryKit tags.

Markdown image

1

![Monument Valley](Monument_Valley.jpg)

Not:

1

/assets/posts/monument-valley/Monument_Valley.jpg

The system automatically resolves the full path.

If an image doesn’t load, check that the folder name matches media_subpath exactly.

5. Preview Your Post

Open your post in the StoryKit Editor and select its preview pane. Viewers update as you edit.

6. Edit, Preview, and Save

Write in the editor, inspect the live preview, then save your changes to your GitHub branch. A preview does not publish the post; GitHub Pages rebuilds after changes reach the publishing branch.

7. StoryKit Features

A basic post is created using plain text and standard Markdown tags. For general Markdown and theme formatting topics, see the official Chirpy documentation.

Using the StoryKit extensions interactive images, maps, videos and more can easily be added to a post using simple tags. More information on the StoryKit extensions can be found in the following guides.

8. Publishing

When satisfied:

Change:

1

published: true

Commit.

The public site updates after GitHub completes its normal rebuild (typically in 1-5 minutes).

9. Troubleshooting

Preview outdated? Wait a few seconds and reload again.

API rate limit warning? Check your GitHub sign-in in the editor.

Images not showing? Check:

  • media_subpath
  • Folder name
  • Exact filename match

Embed shows placeholder? Confirm required _includes/embed/ files exist.

Final Author Checklist

  • Correct filename format
  • Front matter complete
  • media_subpath matches folder exactly
  • Images uploaded
  • Only filenames used
  • Every viewer that action links target has an id
  • published: true when ready

More help: Troubleshooting Guide.