Documentation

Changelog Pages

A changelog page keeps your API consumers informed about what changed between releases. Routebase can write much of it for you: because your documentation embeds pinned snapshots of published API specs, it can compare spec versions and generate categorized changelog entries — including breaking-change flags and migration hints.

Creating a changelog page

  1. In the content tree, choose New Page → Changelog ("Version history with categorized entries"). A documentation version can have one changelog page.
  2. Pick a template: Standard (Added/Changed/Fixed sections), Keep a Changelog (the standard Keep a Changelog format with versioned entries), or Release Notes (user-friendly, feature-focused format).
  3. Click Create Page.

The changelog is a normal page — edit it with the full rich text editor, organized by whatever convention your template established (typically version headings with Added, Changed, Removed, Fixed, Deprecated, and Security sections).

A changelog page in the editor with the Generate button in the header

Auto-generating entries from spec changes

Changelog pages have an extra Generate button in the page header (visible in editable versions). It opens Generate Changelog from Spec Changes: "Automatically create changelog entries by comparing API specification versions."

  1. Select API Specification — the dialog lists the API specs embedded in this documentation version, each showing which spec version it is pinned to. If none are embedded yet, you'll be prompted to add a spec first — see Documentation Overview.
  2. Click Generate. Routebase compares the spec versions and produces a preview of entries.
  3. Review the preview. Each entry shows:
    • a category badge — Added, Changed, Removed, Fixed, Deprecated, or Security;
    • a classification badge for breaking or deprecated changes, with summary counts at the top (e.g. "3 Breaking");
    • a migration hint where one applies.
  4. Use the checkboxes (or Select All / Deselect All) to pick which entries to keep, then click Import N Entries.

The selected entries are inserted into the changelog page as Markdown, where you can reword, reorder, or expand them like any other content.

Tips

  • Generate against a draft documentation version, polish the wording, then take the version live — published versions are immutable, see Versioning.
  • After updating a pinned spec snapshot to a newer release (via the update banner or when cloning a version), run Generate to capture exactly what changed in that release.
  • Breaking and deprecated entries deserve extra context — add migration steps or link to a dedicated migration guide page.