Verse Laravel Package

Getting Started

verse is a Laravel package for turning Markdown content (pages, articles, tag and archive listings) into a built site. Start with the binary Composer exposes rather than guessing at an Artisan command:

composer require <vendor>/verse
vendor/bin/verse --version
vendor/bin/verse build

First places to look:

1. verse.yaml at the project root — the single source of truth for content locations, output, and now sitemap behaviour.
2. The build output directory — confirm where build writes the generated HTML and, as of v0.3.0, sitemap.xml.
3. vendor/bin/verse --version — verify which release you are actually running before filing issues or comparing behaviour against docs.

First useful use case: a docs or blog site generated in CI. Author pages/articles in Markdown, run verse build, and deploy the output. With v0.3.0 the build also emits a sitemap covering published pages, articles, archive and tag pages, so a deployable SEO-complete site now comes out of a single command.

Implementation Patterns

Content-to-deploy pipeline. Treat verse build as the only build step. A typical workflow:

# local
vendor/bin/verse build && <serve the output directory>

# CI (deploy job)
composer install --no-dev
vendor/bin/verse build
# upload generated output, including sitemap.xml

Sitemap as a build artefact. Since v0.3.0 the sitemap is generated, not authored. Don't commit it as source; let the build produce it alongside the HTML so it always matches the published set of pages, articles, archives and tags.

Opting out cleanly. If you maintain a hand-written or third-party sitemap (e.g. from a Laravel route or another generator), disable the built-in one in verse.yaml:

sitemap: false

This is the supported escape hatch and should be set deliberately rather than after discovering a conflict in production.

Version reporting in bug reports. When reporting issues, include the output of vendor/bin/verse --version. On a tagged install this is the Composer-installed version; on a main checkout it prints something like dev-main (f8d2498), which is the information maintainers need to reproduce against a commit.

Tag and archive pages. Because these are generated from content metadata, keep tags consistent in front matter — they drive both the listing pages and the sitemap entries. Adding a tag creates new URLs and new sitemap entries on the next build.

Gotchas and Tips

• public/sitemap.xml conflict (v0.3.0). A pre-existing public/sitemap.xml now collides with the generated sitemap. Decide explicitly: delete yours to use the generated one, or set sitemap: false to keep yours. Don't leave both in place and assume one wins.
• Sitemap reflects published content only. Drafts and unpublished articles should not appear; if they do, check the publish flags in front matter before assuming a sitemap bug.
• Verify absolute URLs. Generated sitemaps are only useful if the base/site URL in verse.yaml is correct for the target environment. Check the first few <loc> entries after the first build, especially in staging vs production.
• --version semantics differ by install type. dev-main (f8d2498) is expected on a branch checkout, not a bug. Don't build release-version checks (or CI assertions) around the output string; use composer show when you need the installed package version programmatically.
• Clean builds. If removed pages linger in the output directory, clear it between builds — stale files can survive and be picked up by sitemap or deploy steps.
• Upgrade check. v0.3.0's only breaking-adjacent change is the sitemap conflict. Before upgrading, grep your repo for public/sitemap.xml and decide the configuration up front; no other migration steps appear necessary.
• Extension point to watch. verse.yaml is the intended control surface — prefer config switches like sitemap: false over post-processing or deleting generated files in scripts, so future releases don't reintroduce the conflict.