> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Show Content on Your Website

> Three ways to put your published changelog, blog posts, and knowledge base on your own site

## Overview

Publishing a changelog, blog post, or knowledge base article in Shipstar makes it available from the public API under a stable slug. It shows up on **your** website once you add one of the integrations below. Pick by how much you care about search engines and AI crawlers seeing the content:

|                         | Embed widget                | Agent-built page           | API / RSS                |
| ----------------------- | --------------------------- | -------------------------- | ------------------------ |
| Effort                  | Paste one snippet           | One prompt in Claude Code  | Write your own rendering |
| Crawlable / AI-readable | No (renders in the browser) | Yes (server-rendered HTML) | Up to you                |
| Auto-updates            | Shows one published item    | Every published period     | Every published period   |
| Needs an API token      | No                          | Yes (server-side)          | Yes (server-side)        |

Every published item's **Add to your website** button in the dashboard (Timeline → the published item, or Destinations → Website) generates these snippets with your slug filled in.

## Embed widget

Paste this where the changelog should appear. `data-shipstar-key` is the public slug of the published item — no secrets, safe in client-side HTML.

```html theme={null}
<div id="shipstar-changelog"></div>
<script
  src="https://shipstar.ai/embed.js"
  data-shipstar-key="your-changelog-slug"
  data-container="shipstar-changelog"
  data-theme="auto"
></script>
```

The widget renders inside shadow DOM (your page styles can't leak in), follows the visitor's light/dark preference, and includes an email subscribe form for changelogs.

### Options

| Attribute              | Default           | Meaning                                                                                        |
| ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------- |
| `data-shipstar-key`    | —                 | Public slug of the published changelog, blog post, or knowledge base set                       |
| `data-type`            | `changelog`       | `changelog`, `blog`, `kb`, or `banner`                                                         |
| `data-container`       | script's position | `id` of the element to render into                                                             |
| `data-theme`           | `auto`            | `auto`, `light`, or `dark`                                                                     |
| `data-max-items`       | `10`              | Maximum entries shown                                                                          |
| `data-subscribe`       | `true`            | Show the changelog email subscribe form                                                        |
| `data-search`          | `false`           | Search box (knowledge base)                                                                    |
| `data-branding`        | `true`            | "Powered by Shipstar" link                                                                     |
| `data-initial-article` | —                 | Knowledge base article slug to open first                                                      |
| `data-position`        | `top`             | Banner only: `top` sticks the bar to the top of the page, `inline` renders it where the tag is |
| `data-dismissible`     | `true`            | Banner only: show a close button; a dismissed banner stays hidden until a new one is published |

<Note>
  Because the widget renders in the browser, search engines and AI answer engines (GPTBot, ClaudeBot, PerplexityBot) fetch an empty container. If discoverability matters, use one of the server-side options.
</Note>

<Tip>
  The dashboard's "Published" status links to your site once it knows where the content lives: the embed widget's request carries a `Referer`; a server-rendered page should send `X-Shipstar-Page-Url: https://acme.com/changelog` with its API requests (the agent skill does this for you). You can also set the page URL per content type by hand under **Destinations → Website → Page URLs**.
</Tip>

### Announcement banner

The widget can also show your project's **announcement banner** — a one-line bar (a "New" badge, headline, one sentence, call-to-action) generated from the period's commits, highlighting the most impactful change. Exactly one banner is live per project, and publishing a new one replaces it under the same key, so this snippet is pasted once:

```html theme={null}
<script
  src="https://shipstar.ai/embed.js"
  data-shipstar-key="your-project-banner"
  data-type="banner"
  data-theme="auto"
></script>
```

Put the tag anywhere (even in `<head>`): the bar mounts at the top of `<body>` and sticks while visitors scroll. `data-position="inline"` renders it where the tag is instead; `data-dismissible="false"` removes the close button (a dismissed banner stays hidden for that visitor until a new one is published). Colours follow CSS variables on the mount element — `--ss-banner-bg` and `--ss-banner-text`, plus `--ss-banner-badge-bg` and `--ss-banner-badge-text` for the badge (they default to the inverse of the bar) — so with `data-container` you can theme it on your own element. The badge reads "New" unless your project sets a different default (Destinations → Website → Banner badge, including off) or the banner re-words it or switches it off (in the draft editor, on the schedule, in the Regenerate dialog, or with `badge` / `show_badge` over MCP). When no banner is live the widget renders nothing.

Schedule the banner weekly or monthly from the dashboard's Generate page; the schedule's "Link to" and "Take down after" choices apply to every run. To render it server-side instead, fetch [`GET /api/v1/banner`](/api-reference/banner/get-live-banner) — a `404` means no banner is live.

## Agent-built page (Claude Code)

The `build-changelog-page` skill in the Shipstar plugin builds what shipstar.ai's own changelog does: a server-rendered `/changelog` with per-period permalinks, an RSS feed, and structured data, in your site's stack.

1. Create an API token under **API Tokens** in the dashboard and put it in your site's environment as `SHIPSTAR_API_TOKEN` (server-side only — never in client code).
2. In your site's repository:

```text theme={null}
/plugin marketplace add shipstar-ai/shipstar-plugin
/plugin install shipstar@shipstar
```

3. Prompt:

```text theme={null}
Use the build-changelog-page skill to add a server-rendered /changelog page to this site from my Shipstar changelog. My Shipstar API token is in SHIPSTAR_API_TOKEN.
```

See [Build a changelog page](/mcp/skills/build-changelog-page) for what the skill produces and the invariants it follows.

## API and RSS

Render it yourself from the JSON. With an API token the list endpoints return **your** project's published content, newest first:

```bash theme={null}
curl https://api.shipstar.ai/api/v1/changelogs \
  -H "Authorization: Bearer $SHIPSTAR_API_TOKEN" \
  -H "X-Shipstar-Page-Url: https://acme.com/changelog"
```

`X-Shipstar-Page-Url` is optional: it tells Shipstar where you render the content, so the dashboard's "Published" status links to your page.

Each period carries `period_start`, `period_end`, `headline`, `entries[]` (`category` is `new`, `improved`, `fixed`, or `breaking`), `slug`, and `commit_count`. Single items are public by slug — `GET /api/v1/changelog/{slug}` — and each has an RSS/Atom feed at `GET /api/v1/changelog/{slug}/feed` that needs no authentication. The project-wide feed, `GET /api/v1/changelogs/feed`, is token-scoped like the list.

Reference: [List Changelogs](/api-reference/changelog/list-changelogs), [Get Changelog](/api-reference/changelog/get-changelog), [Changelog Feed](/api-reference/changelog/changelog-feed).