# Markdown Preview

> Render a Markdown file to GitHub-flavored HTML and open a styled local preview (light + dark) in the browser. Use when the user wants to preview markdown, see how a README renders on GitHub, check that relative screenshots or images display correctly, or get a GitHub-like local preview without installing grip or glow.

- Skill: `drn/markdown-preview` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add drn/markdown-preview`
- Raw SKILL.md: https://api.skillmd.com/api/skills/drn/markdown-preview/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: drn (https://skillmd.com/u/drn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/drn/markdown-preview

---


# Markdown Preview

Render a Markdown file the way GitHub would (GFM: tables, task lists, fenced
code) and open a self-contained, GitHub-styled HTML preview with light and dark
support. Rendering goes through `gh api /markdown`, so no local renderer
(grip/glow) is needed — only an authenticated `gh` CLI and `jq`.

The preview is written ALONGSIDE the source file by default. This is
deliberate: relative image paths (e.g. `screenshots/foo.png`) only resolve when
the HTML lives in the same directory as the markdown.

## When to stop and ask

- If no markdown file path is given and none is obvious from context, ask the
  user which file to preview. Do not guess.
- If the file is not a markdown file (`.md` / `.markdown`), confirm before
  rendering.

## Privacy note

`gh api /markdown` sends the file's contents to GitHub over the network. This
is fine for public README / docs content. If the markdown contains anything
sensitive, tell the user it will leave the machine and confirm before rendering.

## Workflow

### Step 1 — Resolve the file

Identify the markdown file path from the argument (`$1`) or conversation
context. Confirm it exists.

### Step 2 — Render and open

Run the render script. `<skill-dir>` is the directory containing this SKILL.md:

```
bash <skill-dir>/scripts/render.sh <file.md>
```

This renders via `gh api /markdown`, writes `<file>-preview.html` next to the
source, and opens it in the default browser (macOS `open`, Linux `xdg-open`,
Windows `start`).

Useful flags:
- `--no-open` — write the preview but do not launch a browser.
- `--out <path>` — choose the output path (requires a value). Use ONLY when the
  markdown has no relative images; a path outside the source directory breaks
  relative `src`.
- `--print-path` — print only the written preview path to stdout (instead of the
  friendly "Wrote preview:" line). Use when chaining or capturing the path.

The script prints the preview path it wrote. Note that path for the cleanup
step — it is `<file>-preview.html` next to the source unless `--out` overrode it.

If the script reports a missing dependency or a failed render, relay the error
and do not retry more than once:
- `gh` not installed → install the GitHub CLI, or fall back to `grip`/`glow`.
- `gh api /markdown` failed → likely an auth issue; suggest `gh auth status`.
- `jq` not installed → install `jq` (required to encode the request body).

### Step 3 — Cleanup

The preview is a temporary artifact and should not be committed. After the user
is done viewing:
- Offer to remove it, using the exact preview path the script reported (the
  default is `<file>-preview.html`; it differs when `--out` was used). Auto-run
  of `rm` is pre-approved only for the default `*-preview.html` name; removing a
  custom `--out` path will prompt for confirmation, which is fine.
- If the file sits inside a git repository, optionally suggest adding
  `*-preview.html` to `.gitignore` so regenerating it does not leave untracked
  files (this was the original pain point this skill was built to avoid).

To re-preview after editing the markdown, just rerun Step 2 — it overwrites the
existing preview.