Skip to content
shipdot

Getting started

shipdot has three pieces: Markdown entries in your repository, the CLI that compiles them into shipdot.json, and the <ship-dot> web component that shows them in your app. You need Node.js 24 or newer for the CLI.

1. Create the config and a first entry

Section titled “1. Create the config and a first entry”

Run this in the root of your web app:

Terminal window
npx @shipdot/cli init

It creates:

  • shipdot.config.json with sensible defaults (outDir is public/, or static/ if that folder exists).
  • .shipdot/entries/<today>-welcome.md, an example entry.

Existing files are never overwritten. Add --locales en,es if you plan to translate.

2. Write entries and build

Section titled “2. Write entries and build”

An entry is a Markdown file with frontmatter:

.shipdot/entries/2026-10-14-export-excel.md
---
date: 2026-10-14
type: new            # new | improved | fixed
title: Export to Excel
target: "#btn-export" # optional: puts a hotspot on this element
---
You can now export any report to Excel with one click.

Compile the entries:

Terminal window
npx @shipdot/cli build

This validates every entry, renders Markdown to sanitized HTML and writes public/shipdot.json, public/llms.txt and public/llms-full.txt. Add it to your build script so the feed is always fresh:

package.json
{
  "scripts": {
    "build": "shipdot build && vite build"
  },
  "devDependencies": {
    "@shipdot/cli": "^0.1.0"
  }
}

3. Add the widget

Section titled “3. Add the widget”

From a CDN:

<script type="module" src="https://unpkg.com/shipdot@0.1"></script>
<ship-dot src="/shipdot.json"></ship-dot>

Or from npm (npm install shipdot), then import it once on the client:

import 'shipdot'

That’s it. Users see a bell with an unread count. When an unread entry has a target, a pulsing dot appears on that element.

Next steps

Section titled “Next steps”