How to github-themed changelog.md renderer
- Step 1Load CHANGELOG.md — Paste the changelog or upload the file. One file per run.
- Step 2Run the render — Click Run. marked converts the Markdown with GFM and the GitHub dark theme is applied. No options to set.
- Step 3Review the unreleased section — Read the top
## [Unreleased]block first — confirm every entry that should ship is present and grouped under the right Added/Changed/Fixed heading. - Step 4Check the compare links — Scroll to the reference-link block at the bottom and confirm the version links are clickable and point at the right compare ranges.
- Step 5Fix in source and re-run — Correct any miscategorised or missing entries in the source file, paste again, and re-render until the notes are accurate.
- Step 6Distribute or archive — Copy the HTML for a release page, or download
<name>-github.htmlto email stakeholders. For a print/PDF archive use md-to-pdf-modern; for a self-contained HTML file use md-to-html.
Keep-a-Changelog elements and how they render
Behaviour for standard Keep-a-Changelog constructs under marked 14.1.4 default config plus the dark Primer theme.
| Changelog construct | Renders as | Notes |
|---|---|---|
## [1.2.0] - 2026-06-01 | Heading; version is a link if a reference def exists | The bracketed version resolves to its [1.2.0]: URL definition |
### Added / ### Fixed etc. | Sub-heading | Section grouping stays visually clear |
| Bulleted entry lists | Styled <ul> | Nested entries keep their indentation |
[1.2.0]: https://...compare/... | Reference definition — link target | Preserved and resolved; does not print as visible text |
PR / issue refs like (#123) | Plain text | Not auto-linked — #123 is not resolved to a URL |
[!NOTE] callout in an entry | Literal blockquote text | Not a callout here |
Inline code in entries (` --flag `) | Monospaced code span | Renders correctly |
Pick the right output for the job
This tool emits GitHub-styled HTML. Other siblings serve archive and document needs better.
| Goal | Best tool | Why |
|---|---|---|
| Review notes before tagging | This tool | GitHub-styled preview, fast |
| Email a styled copy to stakeholders | This tool / md-to-html | HTML out; md-to-html inlines CSS for offline |
| Archive a print-ready PDF | md-to-pdf-modern | Print engine, page margins |
| Paste release notes into Slack | md-to-slack | Slack mrkdwn dialect |
| Paste into a Jira release ticket | md-to-jira | Jira wiki markup |
Cookbook
Real Keep-a-Changelog snippets and what marked produces inside the GitHub-dark wrapper. Boilerplate <head> omitted.
A version section with grouped entries
The canonical Keep-a-Changelog shape. Heading, dated, with Added/Fixed sub-sections.
Input: ## [1.4.0] - 2026-06-10 ### Added - Dark mode toggle ### Fixed - Crash on empty config Output body (abbreviated): <h2>[1.4.0] - 2026-06-10</h2> <h3>Added</h3> <ul><li>Dark mode toggle</li></ul> <h3>Fixed</h3> <ul><li>Crash on empty config</li></ul>
Reference-style compare links resolve
Keep-a-Changelog puts the version-to-URL map at the bottom. marked resolves these so the bracketed versions become links.
Input (excerpt): ## [1.4.0] - 2026-06-10 ... [1.4.0]: https://github.com/acme/acme/compare/v1.3.0...v1.4.0 [1.3.0]: https://github.com/acme/acme/compare/v1.2.0...v1.3.0 Output: the '[1.4.0]' in the heading becomes a clickable link to the compare URL; the definition lines themselves produce no visible text.
Unreleased section at the top
Most changelogs keep a running [Unreleased] block. It renders like any other version heading.
Input: ## [Unreleased] ### Changed - Bumped minimum Node version to 20 Output body: <h2>[Unreleased]</h2> <h3>Changed</h3> <ul><li>Bumped minimum Node version to 20</li></ul>
Issue refs are NOT auto-linked
On github.com, #123 links to the issue. marked does not do that resolution, so it stays plain text.
Input: - Fixed timeout on large uploads (#412) Output body: <li>Fixed timeout on large uploads (#412)</li> The (#412) is plain text. To link it, write a full Markdown link: [#412](https://github.com/acme/acme/issues/412).
Inline code in an entry
Flag and option names in backticks render as code spans, styled by Primer.
Input: ### Deprecated - `--legacy-output` flag; use `--format=json` instead Output body: <h3>Deprecated</h3> <ul><li><code>--legacy-output</code> flag; use <code>--format=json</code> instead</li></ul>
Edge cases and what actually happens
Issue / PR references are not auto-linked
Expected#123 and @user are not resolved to URLs — that linking is server-side on github.com. They render as plain text. Use full Markdown links ([#123](url)) in the source if you want them clickable in the rendered notes.
Compare links resolve only if defined
Expected## [1.2.0] becomes a link only when a matching [1.2.0]: URL reference definition exists in the file. Miss the definition and the bracketed version renders as plain text. Keep the reference block in sync with your version headings.
Output styling needs internet
By designThe dark Primer CSS is a CDN <link>, not inlined, so a saved changelog file is unstyled offline (the structure is intact). For an offline or emailable file, use md-to-html; for an archive, md-to-pdf-modern.
Theme is dark-only
By designNo light toggle. Release pages that use a light theme will show different colours, though the structure is identical. Edit the downloaded <link> for a light variant if a stakeholder needs it.
GitHub alert callouts stay literal
Not supportedIf a changelog entry uses > [!WARNING] for a breaking-change notice, it renders as a plain blockquote with [!WARNING] visible — not a coloured callout. Phrase breaking-change notices as bold text or a clear heading for portable emphasis.
Reference definitions with broken URLs
Expectedmarked does not validate that a compare URL exists — a typo'd compare/v1.1.0..v1.2.0 (one dot) still renders as a link to a 404. Validate links with md-link-validator before publishing.
Footnotes in a changelog break
Not supportedIf you footnote a deprecation rationale with [^1], it will not link — marked default has no footnotes. Inline the rationale in parentheses instead.
Very long changelog over the cap
rejectedA multi-year changelog can be large. Free tier caps at 500,000 characters / 1 MB and rejects bigger input. Pro raises it to 5,000,000 / 10 MB; or split the history with md-splitter and render the recent section.
Multiple changelogs at once
rejectedOne file per run. To render a combined monorepo changelog, merge the per-package files with md-merger first.
Empty Unreleased section
ExpectedA ## [Unreleased] heading with no entries renders the heading with nothing under it — a useful visual cue that you forgot to log a change before tagging.
Frequently asked questions
Does this support the Keep-a-Changelog format?
Yes. The standard ## [version] - date headings and ### Added/Changed/Fixed/Removed/Deprecated/Security sub-sections render as a clean hierarchy with GitHub's styling. The reference-style compare-link block at the bottom is resolved so version headings become clickable.
Will my compare-version links work?
Yes, when the reference definition exists. [1.2.0]: https://github.com/acme/acme/compare/... is resolved by marked, so ## [1.2.0] in the heading becomes a clickable link. Keep the definition block in sync with your headings or the version renders as plain text.
Are issue references like #123 auto-linked?
No. marked does not resolve #123 or @user to URLs — that is github.com server-side behaviour. Write a full Markdown link ([#123](url)) in the source if you want it clickable in the rendered notes.
How do I export the changelog to PDF for an archive?
Use md-to-pdf-modern, which renders directly to a print-ready PDF. This tool only emits HTML.
Can I get a self-contained HTML file to email stakeholders?
This tool links the theme from CDN, so a saved file needs internet to style. For a portable, offline file with inlined CSS, use md-to-html.
Is the changelog uploaded anywhere?
No. Conversion is entirely in-browser, so entries describing not-yet-public fixes stay on your machine until you choose to publish. Sanitise with md-secret-redactor if an entry mentions internal endpoints or tokens.
Can I paste these release notes into Slack or Jira?
Use the dedicated dialect converters: md-to-slack for Slack mrkdwn and md-to-jira for Jira wiki markup. This HTML tool is for web display.
Is there a light theme for a light-themed release page?
Not in the tool — it is dark-only. Structure is identical in any theme. To produce a light file, edit the downloaded <link> to the light Primer build.
What are the size limits?
Free: 1 MB / 500,000 chars / 1 file. Pro: 10 MB / 5,000,000 / 10. Pro-media: 50 MB / 20,000,000 / 50. Developer: 500 MB / unlimited. A long history may need Pro, or split it with md-splitter.
Do breaking-change `[!WARNING]` callouts render as boxes?
No — [!WARNING] shows as literal text in a plain blockquote. For portable emphasis on a breaking change, use a bold lead-in or a dedicated heading instead.
How do I check the compare URLs are not broken?
Run md-link-validator over the changelog — marked will happily render a typo'd compare URL as a link to a 404, so validate before publishing.
Can I combine per-package changelogs in a monorepo?
Merge them into one file with md-merger, then render the combined file here for a single release-notes view.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.