Step 1 — Add Bookmarklet to Browser

This bookmarklet lets you preview any markdown post from this site's GitHub repository — rendered with full Chirpy layout — without waiting for a GitHub Pages build.

🔖 Preview on GitHub

Drag the button above to your bookmarks bar

  1. Make sure your bookmarks bar is visible (Chrome: ⌘⇧B / Ctrl+Shift+B)
  2. Drag the "Preview on GitHub" button above into your bookmarks bar
  3. Navigate to any .md file in your repo on GitHub (e.g. github.com///blob/main/_posts/...md)
  4. Click the bookmarklet — the preview opens in a new tab
💡 The bookmarklet only works on GitHub blob URLs for .md files in this repository. It will show an alert if clicked on any other page.

Step 2 — Add a GitHub Token (PAT)

Without a token, GitHub limits you to a handful of preview loads per hour. Adding a token raises this to 5,000 — effectively unlimited for normal use.

Create the token:

  1. Go to github.com/settings/tokens/new (sign in if prompted)
  2. In the Note field type: Jekyll Preview
  3. Under Expiration choose No expiration
  4. Scroll down — do not check any boxes
  5. Click Generate token
  6. Copy the token that appears — it starts with ghp_

If you also use the StoryKit editor, tick the repo box at step 4 instead of leaving everything unchecked. The editor and the preview tool share the same saved token, and a scopeless token can raise the rate limit but cannot read private repositories or commit — so the editor would fail to save. One classic token with repo serves both tools.

Note this is a classic token (the page above), not a fine-grained one. A fine-grained token is tied to a single resource owner and cannot reach repositories you merely collaborate on, which makes commits fail even though the token looks valid.

⚠️ You won’t be able to see this token again after you leave the page. Copy it now.

Save the token in the preview tool:

  1. Open your preview page at https://rsnyder.github.io/storykit-starter/preview
  2. Click the ⚙ Config button in the top bar
  3. Enter 1 and press OK
  4. Paste your token and press OK

✅ The token is saved in your browser. You won’t need to enter it again unless you clear your browser data or switch to a different browser.

What the Preview Can and Can’t Show

The preview tool renders your post with a fast, lightweight simulation of the real site build. It is accurate for the things authors change most — text, front matter, viewer tags, captions, action links — but it is not a pixel-perfect copy of the published site. Keep these expectations in mind:

What previews accurately:

  • Your Markdown text, headings, footnotes, and formatting
  • Front matter changes (title, description, images, StoryKit settings)
  • Viewer includes — images, maps, comparisons, videos — with your parameters
  • Action links and entity popups (they run the same code as the live site)

Where small differences are possible:

  • Unusual Markdown edge cases. The preview uses a different Markdown engine than the published site. Everyday writing renders identically; rare constructs (exotic attribute lists, complex tables) can differ slightly. The published site is always the authority.
  • Site-wide features are absent. The preview builds only your one post, so related-post lists, tag pages, search, and comments don’t appear.
  • A just-committed change can take a moment. The preview reads your file from GitHub’s servers, which can lag a few seconds (occasionally a few minutes) behind a commit. Reload again if you see stale content.
  • The preview shows committed content only. Edits still open in the GitHub editor don’t appear until you commit them.

One rule of thumb: if something looks wrong in the preview, first check it on the published site after the next deploy. Investigate further only if it’s wrong there too.

For framework developers: the preview loads the site’s JavaScript and CSS from the deployed site, so edits to those files aren’t visible in preview by default. Add ?dev to the preview URL to load them from a local Jekyll server (http://localhost:4000, or ?dev=<origin> for another address) while developing.