readme-preview

Preview, validate, and prepare your README for npm and GitHub before publishing.

readme-preview helps you:

• 👀 Preview how Markdown renders
• 🧹 Rewrite relative assets & links to working raw URLs
• ✅ Lint & validate README quality (CI-ready)
• ⚡ Bootstrap docs & CI with a single init command

Designed to be tiny, fast, and zero-config.

Install

No install required:

npx readme-preview

Or add as a dev dependency:

npm i -D readme-preview

Quick Start

Preview your README in a browser:

npx readme-preview

Run CI-style validation:

npx readme-preview check --strict

Bootstrap README badges + GitHub Action:

npx readme-preview init --assets

Commands

preview (default)

Render README in a local browser preview.

npx readme-preview

Options:

--file <path>        Markdown file (default: README.md)
--port <number>      Preview port (default: 4173)
--no-open            Do not open browser
--theme <npm|github> Visual theme (default: npm)
--branch <name>      Git branch for raw URLs (default: HEAD)
--base-url <url>     Override raw base URL
--rewrite-links      Rewrite relative markdown links

Examples

Preview a docs README:

npx readme-preview --file docs/README.md

Use GitHub theme:

npx readme-preview --theme github

Rewrite links + images using main branch:

npx readme-preview --branch main --rewrite-links

Preview GitLab repo:

npx readme-preview --base-url https://gitlab.com/user/repo/-/raw/main/

build

Generate static HTML preview:

npx readme-preview build

Output:

.readme-preview/index.html

Useful for:

• CI artifacts\
• documentation previews\
• static hosting

check

Run README validation rules.

npx readme-preview check

Exit code:

• 0 → pass\
• 1 → issues found

Strict mode

npx readme-preview check --strict

Strict checks include:

• Missing H1 title
• Relative images
• README too short
• Missing code blocks
• Missing description under H1
• Raw HTML usage
• Missing Install section
• Missing Usage section

Perfect for CI enforcement.

init

Bootstrap README quality setup.

npx readme-preview init

Creates or updates:

• GitHub Action workflow\
• README badges section\
• Screenshot section\
• Quick start examples

Options

--assets           Add placeholder screenshot
--workflow-only    Only create GitHub Action
--readme-only      Only patch README
--force            Overwrite existing files
--workflow-name    Custom workflow name

Examples

Full setup:

npx readme-preview init --assets

Only CI workflow:

npx readme-preview init --workflow-only

Overwrite existing:

npx readme-preview init --force

Asset & Link Rewriting

Relative paths like:

![Demo](./assets/demo.png)
[Guide](./docs/guide.md)

Can be rewritten to:

https://raw.githubusercontent.com/user/repo/HEAD/assets/demo.png
https://raw.githubusercontent.com/user/repo/HEAD/docs/guide.md

Controlled by:

--branch
--base-url
--rewrite-links

Works with:

• GitHub\
• GitLab\
• Self-hosted repos

Themes

Switch rendering style:

--theme npm
--theme github

Useful for matching:

• npm package page\
• GitHub README view

CI Integration

Typical GitHub Action step:

- name: README checks
  run: npx readme-preview check --strict

This ensures:

• Broken docs never reach main
• README quality stays high
• Contributors follow standards automatically

Why use readme-preview?

Most projects discover README problems after publishing.

This tool lets you:

• Catch rendering issues before npm release
• Enforce documentation quality in CI
• Provide working screenshots & links
• Bootstrap professional README structure instantly

All in a tiny CLI with no config .

Philosophy

Small tools.
Real problems.
Zero friction.

License

MIT