Markdown Files

Instead of GitHub releases, the plugin can read the changelog from Markdown files in your repository. The changelog is then versioned and reviewed with your code, ships with every deploy and needs no GitHub token.

Files can be split by audience, so every panel shows its own changelog: admins see admin features, customers only what concerns them.

Setup

Point the plugin at the changelog folder and, optionally, an audience:

// AdminPanelProvider
$panel->plugins([
    ChangelogPlugin::make()
        ->files(base_path('changelog'), audience: 'admins'),
]);

// CustomerPanelProvider
$panel->plugins([
    ChangelogPlugin::make()
        ->files(base_path('changelog'), audience: 'customers'),
]);

Run php artisan changelog:get in your deployment script. It clears the cache and reads the files of every panel.

Folder Structure

changelog/
├── admins/
│   └── de/
│       ├── v2.14.0.md
│       └── v2.15.0.md
├── customers/
│   ├── de/
│   │   └── v2.15.0.md
│   └── en/
│       └── v2.15.0.md
└── images/
    └── v2.15.0/
        └── new-search.png

->files(string $path, ?string $audience = null, ?string $locale = null) reads the files from:

Folder	When
{path}/{audience}/{locale}	$locale is passed, or it's the app locale
{path}/{audience}/{fallback locale}	the folder above doesn't exist, using app.fallback_locale
first subfolder of {path}/{audience}	neither locale folder exists
{path}/{audience}	there are no subfolders

Without an audience, {path} takes its place. Audience and locale folders are both optional: ->files(base_path('CHANGELOG')) reads CHANGELOG/*.md directly.

File Format

One file per release. The file name is the version, e.g. v2.15.0.md. Releases are sorted by version, newest first, and the version is compared with the user's last seen version when you use ->trackUserVersion().

---
date: 2026-09-18
title: Autumn Update
---

## Search clients by email

The global search now finds clients by their email address.

![Global search with results](../../images/v2.15.0/new-search.png)

## More improvements

- Payouts can be sorted by therapist.

## Fixes

- The calendar shows appointments with their real duration.

Frontmatter

Optional. Flat key: value pairs between --- lines.

Key	Default	Description
date	file modification date	Release date (YYYY-MM-DD), shown next to the version.
title	the version	Heading of the release.
summary	the feature headings	One line shown while the release is collapsed. By default, all ## headings followed by text instead of a list, e.g. Search clients by email, but not More improvements.

Body

GitHub-flavoured Markdown. Headings are shifted down one level when rendered (## becomes h3), so start with ##.

Images

Images with a relative path are resolved from the Markdown file, copied to the asset storage (public disk, changelog/files/… by default) and linked from there. That way images can live next to the changelog, outside your public folder.

Only files inside the changelog folder ($path) are copied. Absolute URLs are left as they are.

Writing the files

The files can be written by hand or by any tool. The plugin also ships AI skills that write them for you.

AI Skills

With Laravel Boost installed, select pxlrbt/filament-changelog when running php artisan boost:install, or add it to packages in boost.json and run php artisan boost:update. Boost installs three skills for your agent (e.g. into .claude/skills/):

Skill	What it does
/release-init	Looks at your project (panels, UI language, test users, repo visibility, deploy workflows), asks about the audiences and writes changelog/config.json.
/release-prepare	Collects the pull requests since the last release, ranks them, takes framed screenshots of new features and writes one file per audience plus internal release notes into changelog/ for review.
/release-publish	Commits changelog/, pushes, tags the release with its notes and creates the GitHub or Forgejo release. Only runs when you invoke it, because a release may trigger a deploy.

Requirements: the GitHub CLI (gh) for repositories on GitHub or the Forgejo CLI (fj, logged in with fj auth login) for repositories on Forgejo, and for screenshots Node.js and Google Chrome. /release-prepare installs its screenshot dependency (playwright-core) into the skill folder on first use.

Config

changelog/config.json describes the audiences for the skills. The plugin itself only reads the Markdown files.

Key	Description
repository.visibility	public links issues and PRs in the audience files, private only in the internal release notes.
releaseNotes.locale	Language of changelog/releases/<version>.md, the internal notes used for the GitHub or Forgejo release.
audiences.<name>	One per audience folder: locales, readers, technicalKnowledge, includeInternalChanges, form (du/Sie), paths and terminology.
screenshots	Optional. baseUrl, logins per role with url and email, password, css to hide dev toolbars, and framing (viewport, padding, background).