StoryKit Editor help

A browser-based Markdown editor for StoryKit posts: live preview, viewer-tag autocomplete, drag-and-drop media, Wikidata entity linking, and GitHub sync.

Overview

The editor runs entirely in your browser — there is nothing to install and no server-side account. Documents are saved automatically (about two seconds after you stop typing) to your browser's local storage; the badge on each document tells you how it relates to GitHub (see sync states). One editor serves every StoryKit repository: connect it to GitHub once and you can open, edit, and commit files in any repository you can write to.

Edit / Split / Preview — switch with the top-bar buttons or ⌘E. The preview is a high-fidelity render of the published page, including working viewers (click an image viewer to zoom; shift-drag in the expanded view to copy region coordinates).
Command palette — ⌘K reaches every action from the keyboard.
Audit — click the issue counter in the status bar (or ⌘K → Audit document) for a full report of StoryKit syntax problems: malformed tags, unknown attributes, curly quotes inside tags, missing closing quotes, broken action links, unclosed Markdown links, and front-matter problems — both YAML syntax and semantics (unknown property names get did-you-mean suggestions; value shapes like an empty image.path are checked). Click a line number to jump to the problem.
Spell check — StoryKit-aware: only prose is checked (front matter, tags, code, and URLs are skipped). Click a squiggled word for suggestions and Add to dictionary; findings also appear in the Audit report. The English dictionary loads once (~1 MB) and is cached. ⌘K → Toggle spell check turns it off.
Scroll sync — in Split view the two panes follow each other, anchored at headings and viewers (approximate in long prose between them). Toggle it from the palette: Toggle split-view scroll sync.
Document list — the left pane: create (+ New), import a local .md file (Import…), or open a file that already exists on GitHub (Open…, drag-and-drop, or the bookmarklet). The highlighted row is the document you're editing.

Your drafts live in this browser. They survive reloads and restarts, but clearing site data deletes them — commit to GitHub (or Export) anything you care about.

Connecting to GitHub (one-time token setup)

To read private repositories and commit changes, the editor needs a GitHub personal access token — think of it as a password you mint specifically for this purpose. GitHub offers two kinds, and for this editor you want a classic token. It takes about two minutes:

Open github.com/settings/tokens/new (GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)).
Note: anything memorable, e.g. storykit-editor.
Expiration: your choice — 90 days is a sensible default. (When it expires, sync starts failing with an auth error; just mint a new token and save it here.)
Select scopes: tick repo — the top-level checkbox, which selects the whole group. That covers reading and committing. If you only ever author in public repositories you can tick just public_repo instead.
Click Generate token and copy the value (it's shown only once).
Back in the editor: click GitHub above the document list to open the sync panel, paste the token, and click Save token. (The status-bar chip and any document's Sync with GitHub button open the same panel.) Do this before opening a file from a private repository — the editor can't read one without a token.

Why classic rather than fine-grained? A fine-grained token is issued against a single resource owner — you, or one organization — so it can only reach repositories that owner controls. If you are a collaborator on someone else's repository, a fine-grained token cannot be granted access to it at all, and for an organization's repositories the organization has to enable fine-grained tokens (often with an admin approving each one). The symptom is confusing: reading may appear to work while every commit fails. A classic token with the repo scope reaches every repository you can already push to, including ones you collaborate on. The trade-off is that it is broader — it is not limited to chosen repositories — so set an expiration, and use Forget token when you are done on a shared machine.

The token is stored only in this browser's local storage and is sent only to api.github.com. Nothing else ever sees it, and Forget token removes it. Public repositories can be opened without a token; committing always requires one.

Working with GitHub

Opening an existing file

Open… (document list) — paste a GitHub file URL (github.com/<owner>/<repo>/blob/<branch>/<path>) or, once a repository is connected, just a repo path like _posts/2026-01-01-my-post.md.
Drag-and-drop — drag a file link from any GitHub page straight into the document list.
Bookmarklet — see below.

Opening is idempotent: if the file is already in your list, the existing copy is focused instead of duplicated — your local edits are never overwritten.

Binding, committing, pulling

Each document remembers its own repository, branch, and path (its binding). The sync panel shows the binding, lets you change it, and offers Commit (push your version to GitHub) and Pull (replace your buffer with GitHub's version — a snapshot of your text is kept in the revision history first, so pulling is never destructive).

What the badges mean

Badge	Meaning
Local only	Not connected to GitHub yet.
Synced	Your copy matches GitHub (the Sync button is disabled — nothing to do).
Local changes	You've edited since the last commit — commit when ready.
Remote changed	GitHub has newer changes (someone else committed) — pull, or commit to see the conflict dialog.
Conflict	Your commit raced someone else's. Choose Keep mine, Take remote, or view the diff — whichever you pick, a snapshot of your text is saved first.

The "Edit in StoryKit" bookmarklet

The fastest route from GitHub to the editor. Drag this link to your browser's bookmarks bar:

Edit in StoryKit

Then, on any Markdown file page on GitHub (a blob or edit URL), click the bookmark: the editor opens with that file loaded and bound — ready to edit, preview, and commit. If the file was already in your document list, it's simply focused.

Bookmarks bar hidden? ⌘⇧B (Chrome/Edge) or View → Always Show Bookmarks Bar (Safari) toggles it. You can also skip the bookmarklet entirely: the editor URL accepts ?open=<GitHub file URL>.

Drag-and-drop media

Drop media into the text where you want the viewer tag inserted:

Wikimedia Commons — drag an image from any Commons page (or paste its URL) and it becomes an image-viewer tag using the compact wc: shorthand, e.g. src="wc:Sunflowers.jpg". The shorthand also works in front matter: image.path: wc:Sunflowers.jpg renders the page header image.
YouTube — drop or paste a video URL (including Shorts) for a video-viewer tag with the id extracted.
Google Maps — drop or paste a Maps URL for a map-viewer tag with the center and zoom extracted.

Pasting one of these URLs as plain text offers a one-click "Paste as StoryKit tag?" affordance instead of inserting the raw URL. The toolbar's Insert viewer menu covers every viewer type with a template tag.

Wikidata entity linking

Select a name or term and press ⌘⇧K: search Wikidata, pick the match, and the selection becomes an entity link like [Charles Darwin](Q1035) — rendered pages show an info popup for it. Hovering an existing QID in the text shows a reference card.

Tips & troubleshooting

The preview looks stale or a just-fixed problem persists — reload the editor tab. A long-lived tab keeps the old renderer in memory until reload.
Sync fails with an authentication error — your token likely expired. Mint a new one (steps above) and save it in the sync panel.
Editing workflow files — committing changes under .github/workflows/ needs the additional Workflows: Read and write token permission; normal StoryKit authoring never does.
Keyboard shortcuts — ⌘K palette · ⌘E cycle Edit/Split/Preview · ⌘⇧K link entity · ⌘B/⌘I bold/italic. (Ctrl on Windows/Linux.)

← Back to the editor