Show draft news in documentation

changelog writes a documentation copy of released history with the current fragments under Draft. Run it before the documentation builder on every pull request. Readers can then review the full pending text before a release; the tracked changelog and fragment files stay untouched. When the fragment directory is empty, the copy has no Draft section.

The output must be a different path from the tracked changelog. Point the documentation site at that output path. The command does not link named fragments to a pull request: that link and the verified human by credits are added after the squash merge, before release preparation.

Shared Markdown changelog

For a repository with multiple packages in one CHANGELOG.md, select one ## package section and its matching fragment directory:

uvx --from release-creator release-creator changelog \
  --format package --package pyproject-fmt \
  --changelog CHANGELOG.md --fragments changelog.d/pyproject-fmt \
  --output pyproject-fmt/docs/changelog.md

The page puts pending entries under ### Draft before that package’s released history. It keeps the released text and its anchors unchanged. Draft headings receive package-specific anchors such as draft-pyproject-fmt and draft-pyproject-fmt-added, so links to them remain stable as new fragments arrive. Each fragment must be one nonempty paragraph named +topic.feature.md or 42.bugfix.md, using a supported release category. A documentation task can call release_creator.changelog.preview.render_preview directly when it needs to convert the resulting Markdown for a Sphinx page. Other fragment files fail the preview; .gitkeep is ignored. A ## heading inside a fenced code example remains in that package’s history.

Knope Markdown changelog

For .changeset/*.md files, use the category names from knope.toml:

uvx --from release-creator release-creator changelog \
  --changelog CHANGELOG.md --config knope.toml \
  --fragments .changeset --output site/data/changelog.md

A changeset with default: security and # Remove a distrusted root appears under the Draft section’s Security heading. Its full text remains visible. The copy retains existing release and category anchors; the draft has draft and draft-security anchors. The command rejects missing front matter, unknown types, and empty summaries.

Towncrier reStructuredText changelogs already have an upstream draft renderer. Enable Towncrier’s Sphinx extension and put its draft directive above the release notes start marker in the tracked RST page:

.. towncrier-draft-entries:: Draft

.. towncrier release notes start

No preview copy or changelog command is needed for those sites.