How to format changelog.md for slack release channels
- Step 1Extract the version section you want to post — The converter processes one input per run. Copy just the latest
## [x.y.z]section from CHANGELOG.md, or use md-splitter at /markdown-tools/md-splitter to break the file into per-version pieces first. - Step 2Convert bare references to full links — Slack does not auto-link
#123or@contributorthe way GitHub does. Before converting, replace bare references with full[#123](https://github.com/org/repo/issues/123)links so they become clickable in the channel (or post in a channel where Slack's GitHub integration auto-links them). - Step 3Paste or upload the section — Use Paste text for a copied section, or Upload file for a per-version
.md(accepts.md,.mdx,.markdown,.txt). - Step 4Run the conversion — Click Run MD → Slack. Version and category headings become bold lines, change bullets pass through, and PR links become
<url|label>. - Step 5Check bullets and links in the result — Confirm the change bullets are intact and PR links are angle-bracketed. Remember bold text written with
**renders italic — use a single asterisk if a callout must be bold. - Step 6Post to #releases — Click Copy or Download (
-slack.txt) and paste into your release channel. Slack's native scheduler accepts the same mrkdwn if you want to time the post.
Changelog constructs and their Slack output
How each Keep-a-Changelog element converts. Reference links and tables need a quick source pass before running.
| Changelog element | Slack output | Status | Pre-conversion action |
|---|---|---|---|
## [1.4.0] - 2026-06-10 | *[1.4.0] - 2026-06-10* (bold line) | Supported | None |
### Added category heading | *Added* (bold line) | Supported | None |
- Fixed cache eviction bullet | - Fixed cache eviction (unchanged) | Supported | None |
[#482](https://github.com/o/r/pull/482) | <https://github.com/o/r/pull/482|#482> | Supported | None |
bare #123 reference | #123 (plain text, no link) | Unsupported | Replace with a full link |
bare @contributor | @contributor (plain text, no ping) | Unsupported | Replace with a link or real Slack mention |
--- between versions | line of 40 ─ characters | Supported | None — useful as a separator |
**Breaking:** callout | _Breaking:_ (italic, not bold) | Quirk | Use a single * for bold |
Per-version posting workflow
Recommended pipeline for posting one release at a time, since the converter takes a single input per run.
| Step | Tool | Purpose |
|---|---|---|
| Split CHANGELOG.md by version | md-splitter (/markdown-tools/md-splitter) | Get one ## [x.y.z] section per file |
Replace bare #nnn with full links | manual / find-replace in source | Make issue/PR references clickable in Slack |
| Convert the section to mrkdwn | md-to-slack (this tool) | Headings → bold, links → <url|label> |
| Validate the PR links resolve | md-link-validator (/markdown-tools/md-link-validator) | Catch dead PR/issue URLs before posting |
Cookbook
Real changelog sections and the exact mrkdwn the converter emits, so your #releases post is predictable on the first paste.
A version section with categories and bullets
A standard Keep-a-Changelog section converts cleanly: version and category headings become bold lines, and the change bullets pass through unchanged as a native Slack list.
Input (CHANGELOG.md section): ## [1.4.0] - 2026-06-10 ### Added - Webhook retries with backoff ### Fixed - Cache eviction under load Output (Slack mrkdwn): *[1.4.0] - 2026-06-10* *Added* - Webhook retries with backoff *Fixed* - Cache eviction under load
Full PR links become clickable
When change entries cite PRs as full Markdown links, the converter rewrites them into Slack's angle-bracket form so the team can jump straight to the diff.
Input (CHANGELOG.md): - Fixed retry storm ([#482](https://github.com/acme/api/pull/482)) Output (Slack mrkdwn): - Fixed retry storm (<https://github.com/acme/api/pull/482|#482>)
Bare references stay plain — fix them first
GitHub renders #123 and @alice as links, but Slack does not, and the converter does not transform them. Replace bare references with full links in the source before converting.
Input (bare references, unchanged by converter): - Resolved #123 reported by @alice Output (still plain text — not clickable): - Resolved #123 reported by @alice Fix the source first: - Resolved <https://github.com/acme/api/issues/123|#123> reported by @alice
Multiple versions separated by a rule
If you post two releases at once, the --- divider between them becomes a box-drawing line, giving the message a clear visual break.
Input (CHANGELOG.md): ## [1.4.0] - New: retries --- ## [1.3.2] - Fix: typo in docs Output (Slack mrkdwn): *[1.4.0]* - New: retries ──────────────────────────────────────── *[1.3.2]* - Fix: typo in docs
A Breaking callout needs a single asterisk for bold
Release notes often flag breaking changes with **Breaking:**. After conversion that is italic. Use a single asterisk in the source so the warning stands out in bold.
Input (CHANGELOG.md): **Breaking:** dropped the v1 auth header. Output (italic, not bold): _Breaking:_ dropped the v1 auth header. Write the source as `*Breaking:*` for Slack bold: *Breaking:* dropped the v1 auth header.
Edge cases and what actually happens
Bare `#123` issue references are not linked
UnsupportedGitHub auto-links #123, but Slack does not, and the converter performs no reference resolution — #123 stays as plain text. Replace bare references with full [#123](url) links in the source before converting, or post in a channel where Slack's GitHub app auto-links them.
`@contributor` shout-outs do not ping
ExpectedA bare @alice in a changelog stays as text and does not notify the user in Slack. To credit a teammate, type a real @-mention in Slack's composer (so it resolves to a user ID) or link to their GitHub profile.
Breaking-change callouts render italic
By designBecause **bold** is reduced to *bold* then to _bold_, a **Breaking:** callout comes out italic. Use a single asterisk (*Breaking:*) in the source so the most important line of the release note is bold.
Embedded comparison/metric tables show as pipes
UnsupportedSome changelogs include a benchmark or compatibility table. Slack has no table element and the converter does not flatten pipes, so the table appears as raw pipe text. Rewrite it as a bulleted list in the source before posting.
Posting the whole file at once
Watch outA full CHANGELOG.md has many version sections; converting all of it produces a very long message that Slack truncates around 40,000 characters. Post one version per message — split the file first with md-splitter at /markdown-tools/md-splitter.
Nested sub-bullets are preserved but not re-indented
PreservedIndented sub-bullets pass through with their original indentation, which Slack renders with limited nesting depth. The converter does not normalise list nesting; if indentation looks off, fix the source list first with md-list-fixer at /markdown-tools/md-list-fixer.
Code-style version tokens get italicised by underscores
Watch outA token like v1_4_0 written in prose can be partially italicised because the italic rule matches _..._. Wrap version tokens or filenames in backticks in the source so they are treated as inline code and left untouched.
Section exceeds the character limit
400 over limitFree tier caps input at 1 MB / 500,000 characters. A single version section is tiny, but converting an entire multi-year changelog can exceed it. Convert one section at a time, or upgrade to Pro (10 MB / 5,000,000 characters).
Frequently asked questions
Will issue references like `#123` link in Slack?
Not by themselves. GitHub auto-links #123, but Slack does not, and the converter leaves bare references as plain text. Convert them to full [#123](url) links in your source first, or post in a channel where Slack's GitHub integration auto-links them.
How do I post just the latest release?
Extract the latest ## [x.y.z] section before converting, since the tool takes one input per run. md-splitter at /markdown-tools/md-splitter can break CHANGELOG.md into per-version files for you.
Do change bullets survive the conversion?
Yes. The converter does not rewrite list markers, so your - Fixed …/- Added … bullets pass through unchanged and render as a native Slack list.
Why is my `**Breaking:**` note italic instead of bold?
The emphasis rule order reduces **bold** to *bold* then to _bold_, which Slack shows as italic. Write the callout with a single asterisk (*Breaking:*) in the source for true Slack bold.
What happens to PR links?
Full Markdown links like [#482](https://github.com/org/repo/pull/482) become Slack's <url|#482> form and stay clickable. Validate that the URLs resolve with md-link-validator at /markdown-tools/md-link-validator before posting.
Can I schedule the release post?
Yes. Slack's native message scheduler accepts mrkdwn-formatted text — paste the converted output into the scheduler dialog and pick a time.
Are version headings preserved as headings?
Slack has no heading element, so ##/### headings become bold lines. That keeps the version and category structure scannable inside a single message.
What about a compatibility table in the changelog?
Slack cannot render tables, and the converter passes pipes through as raw text. Rewrite the table as a short bulleted list in your source before converting.
Are release notes uploaded anywhere?
No. The conversion runs entirely in your browser via the markdown engine. The changelog text is never sent to a server; only an anonymous processed-count metric is recorded for dashboard stats.
What file types and sizes are accepted?
Paste text, or upload a single .md, .mdx, .markdown, or .txt file. Free tier allows up to 1 MB / 500,000 characters; Pro raises that to 10 MB / 5,000,000.
Can I credit contributors with @-mentions?
The converter leaves @name as plain text — it does not ping anyone. Add real Slack @-mentions in the composer after pasting, or link to GitHub profiles instead.
I want the changelog in Jira instead — is there a tool?
Yes. Use md-to-jira at /markdown-tools/md-to-jira to convert the same changelog to Jira wiki markup for a release ticket or comment.
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.