about

ship-notes

A CLI + static site tool that turns structured TOML release files into a human-readable changelog. Write releases in plain text, publish a site, post to GitHub Releases, notify Slack or Discord — all from one command.

INSTALL

npm install -D ship-notes
# or
pnpm add -D ship-notes

QUICK START

  • ship-notes init — interactive setup wizard, creates ship-notes.toml and releases/
  • ship-notes add — scaffold a new release TOML file for the next version
  • ship-notes build — compile all releases into static HTML + Markdown
  • ship-notes preview — start the local SvelteKit dev server
  • ship-notes validate — check all release files for schema errors

COMMANDS

  • ship-notes diff [version] — print one or more releases as Markdown to stdout
  • ship-notes diff v1.0.0..v1.4.0 — print a range of releases
  • ship-notes digest [version] — write an HTML email digest to changelog/
  • ship-notes open — open the configured changelog URL in the system browser
  • ship-notes latest — print the latest version number to stdout
  • ship-notes publish --github — post a release to GitHub Releases via API
  • ship-notes notify — send a release summary to a Slack or Discord webhook
  • ship-notes build --since <version> — build only releases at or after a version

CONFIG

All fields live in ship-notes.toml at the project root.

  • title — site title shown in the header and RSS feed
  • url — public URL of the deployed changelog site
  • repo — GitHub repository URL, used by ship-notes publish
  • releases_dir — directory for TOML release files (default: releases/)
  • output_dir — build output directory (default: changelog/)
  • default_author — author name applied to items with no explicit author; falls back to git config user.name
  • default_author_url — fallback link for author tags when no commit link is present
  • notify_webhook — Slack or Discord webhook URL; can also be set via SHIP_NOTES_WEBHOOK env var

RELEASE FORMAT

Each release is a .toml file in releases/.

version = "1.0.0"
date    = "2026-06-30"
name    = "Optional release name"
summary = "Optional one-line summary shown above the changelog."

[sections.new]

[[sections.new.items]]
text       = "Added something great"
link       = "https://github.com/you/repo/commit/abc123"
author     = "yourname"
author_url = "https://github.com/yourname"

[[sections.new.items]]
text     = "Removed old API"
breaking = true

[sections.fixed]

[[sections.fixed.items]]
text = "Fixed a bug"

Standard section keys: new, fixed, changed, removed. Any custom key also works.

Item fields: text (required), link, breaking, author, author_url. Author tags link to link if set, then author_url, then default_author_url.

SOURCE