<!--
Sitemap:
- [What is Vocs](/introduction/what-is-vocs): Learn why Vocs exists and when to use it
- [Getting Started](/introduction/getting-started): Install Vocs and create your first documentation site
- [Project Structure](/introduction/project-structure): Overview of the structure of a Vocs project
- [Writing Docs with AI](/introduction/writing-docs-with-ai): Use an AI agent to create and maintain Vocs documentation
- [Markdown Extensions](/writing/markdown-extensions): Features and syntax of Markdown in Vocs
- [Code & Syntax Highlighting](/writing/syntax-highlighting): Rich markup and annotations for code
- [Twoslash](/writing/twoslash): Add type-aware annotations to code examples
- [Code Snippets](/writing/code-snippets): Include and reuse code in Markdown
- [Markdown Snippets](/writing/markdown-snippets): Include other Markdown files in MDX
- [React in Markdown](/writing/react): Compose MDX pages with React components
- [Mermaid Diagrams](/writing/mermaid): Render diagrams from text using Mermaid
- [Assets](/writing/assets): Manage images, fonts, icons, and other docs assets
- [Frontmatter](/writing/frontmatter): Configure page metadata, layouts, search, and UI visibility
- [Navigation](/features/navigation): Keep docs navigation synced with routes
- [Search](/features/search): Built-in client-side search powered by MiniSearch
- [Layouts](/features/layouts): Choose and customize page shells for your docs
- [Slots](/features/slots): Inject custom components into the docs shell
- [Theming](/features/theming): Customize colors, typography, spacing, logos, and code themes
- [Tailwind CSS](/features/tailwind): Use Tailwind utilities in Vocs pages and components
- [Dynamic OG Images](/features/dynamic-og-images): Generate social preview images from page metadata
- [Page Feedback](/features/feedback): Collect page-level feedback from readers
- [Redirects](/features/redirects): Preserve old URLs and route legacy paths to new locations
- [API Routes](/features/api-routes): Add server-rendered endpoints to your docs site
- [Agent Support](/features/agent-support): Serve documentation in machine-readable form for AI agents
- [Ask AI](/features/ask-ai): Built-in AI assistant menu on every page
- [MCP Server](/features/mcp-server): Expose your docs and source code to AI assistants
- [Changelog Generation](/features/changelog-generation): Fetch release notes and render a changelog page
- [Site Configuration](/reference/site-config): Reference for options accepted by defineConfig
- [Frontmatter Reference](/reference/frontmatter): All frontmatter fields accepted by a Vocs MDX page
- [Components](/reference/components): Reference for the public React components exported from Vocs
- [Hooks](/reference/hooks): Reference for the React hooks exported from Vocs
- [Changelog](/changelog): Release history for Vocs
-->

# Changelog Generation \[Fetch release notes and render a changelog page]

Vocs can fetch release data from a changelog adapter and render it as a changelog page in your docs.

Out of the box, Vocs includes a GitHub releases adapter and a simple adapter interface for custom sources.

## Configure a Changelog Source

Add a changelog adapter to `vocs.config.ts`:

```ts [vocs.config.ts]
import { Changelog, defineConfig } from 'vocs/config'

export default defineConfig({
  changelog: Changelog.github({ repo: 'wevm/vocs' }),
})
```

With this configuration, Vocs fetches releases from the GitHub Releases API.

## GitHub Adapter

Use `Changelog.github()` to read releases from a GitHub repository.

```ts
import { Changelog } from 'vocs/config'

Changelog.github({
  repo: 'wevm/vocs',
  prereleases: true,
  token: process.env['GITHUB_TOKEN'],
})
```

Use the options as follows:

* `repo`: GitHub repository in `owner/repo` format
* `prereleases`: Include prereleases in the returned changelog
* `token`: Optional GitHub token for authenticated requests and higher rate limits

If you do not pass `token`, Vocs falls back to `GITHUB_TOKEN`.

## Render the Built-in Changelog

Use the `::changelog` directive in an MDX page to render releases from your configured adapter.

```mdx [src/pages/changelog.mdx]
# Changelog

::changelog
```

You can also limit the number of releases shown:

```mdx [src/pages/changelog.mdx]
::changelog{limit=10}
```

This is how the [Vocs changelog page](/changelog) is rendered.

## Custom Adapters

If your releases live somewhere other than GitHub, create a custom adapter with `Changelog.from()`.

```ts [vocs.config.ts]
import { Changelog, defineConfig } from 'vocs/config'

export default defineConfig({
  changelog: Changelog.from({
    type: 'custom',
    async fetch() {
      return [
        {
          version: 'v1.0.0',
          title: 'v1.0.0',
          date: '2026-04-21T00:00:00.000Z',
          body: 'Initial release.',
          url: 'https://example.com/releases/v1.0.0',
        },
      ]
    },
  }),
})
```

Each release should provide:

* `version`: Release tag or version string
* `title`: Human-readable release title
* `date`: ISO timestamp for the release date
* `body`: Markdown release notes
* `url`: Canonical release URL

## Fetch Releases Yourself

For custom pages or layouts, use `Actions.fetchChangelog()` in a server component and render the releases yourself.

```tsx
import { Actions } from 'vocs/server'

export default async function Page() {
  const releases = await Actions.fetchChangelog({ limit: 10 })

  return (
    <div>
      <h1>Changelog</h1>
      {releases.map((release) => (
        <article key={release.version}>
          <h2>
            <a href={release.url}>{release.title}</a>
          </h2>
          <p>{new Date(release.date).toLocaleDateString()}</p>
          <div dangerouslySetInnerHTML={{ __html: release.bodyHtml ?? '' }} />
        </article>
      ))}
    </div>
  )
}
```

`fetchChangelog()` renders each release body from Markdown to HTML before returning it.

## Notes

* If `changelog` is not configured, the built-in changelog renders no releases.
* The `::changelog` directive uses your configured adapter and supports `limit`.
* For a minimal setup, configure `changelog` in `vocs.config.ts` and create a page containing
  `::changelog`.