- 01Inspect the source
- 02Check the renderer
- 03Verify the destination
Each step answers a different question. Verify the final document in its actual destination.
Choose the structure for your readers
Write for people upgrading the project. A useful changelog selects meaningful behavior changes instead of copying a raw commit list. Keep an Unreleased section while development continues, then move entries under a version and date when a release ships.
A small example to try
# Changelog
## [Unreleased]
### Added
- Describe a user-visible capability.
### Fixed
- Explain the symptom that was resolved.Paste this example into the editor and compare the source with its preview. Change one element at a time so you can identify which syntax controls the result.
Check compatibility before sharing
Use Added, Changed, Deprecated, Removed, Fixed and Security categories where relevant. Explain breaking changes and link migration instructions. Verify release links and dates. A changelog is factual release history: do not present an experimental branch as an available product capability.
A practical review checklist
- Check headings and labels explain the content without extra context.
- Test the example in the destination where people will read it.
- Verify links and relative asset paths after moving the file.
- Inspect exported documents separately from the live preview.
- Keep the editable Markdown original alongside distributed copies.
Primary source and further reading
Read the specification or project documentation. Explore the complete Markdown guide and Compatibility Lab.
Want to inspect a small example? Try it in a Markdown preview, then verify your publishing destination.