How to format bug reports for jira tickets
- Step 1Paste or upload the bug report — Use Paste text for a quick report, or Upload file for a
.mdtemplate. Single file only — this tool does not accept a folder of reports. - Step 2Click Run — The converter stashes any fenced stack traces, then rewrites headings, repro-step numbering, bullet lists, inline code, and links in fixed order. No options to set.
- Step 3Confirm the repro steps numbered correctly — Check that your
1. 2. 3.steps became# # #and that nested sub-steps gained an extra#per two-space indent level. - Step 4Check the stack trace block — Verify the trace landed inside
{code:text}…{code}(or{code}if you used a bare fence) and that no characters inside it were altered. - Step 5Copy and paste into the Jira description — Click Copy. In the new-issue dialog, switch the Description field to wiki / text mode and paste, then toggle to the rendered view to verify.
- Step 6Attach screenshots and rebuild any environment table — Drag-drop screenshots onto the ticket as attachments — they are not embedded by the converter. If your report had a GFM environment matrix, rebuild it as
||Field||Value||rows by hand.
Bug-report constructs and their Jira output
How the parts of a typical bug report map through the transform.
| Bug-report element | Markdown | Jira output |
|---|---|---|
| Section heading | ## Steps to Reproduce | h2. Steps to Reproduce |
| Numbered repro step | 1. Open /login | # Open /login |
| Nested sub-step | 1. Enter creds (two-space indent) | ## Enter creds |
| Bullet detail | - Browser: Chrome 124 | * Browser: Chrome 124 |
| Inline command | npm run e2e | {{npm run e2e}} |
| Stack trace fence | ` text … ` | {code:text}…{code} |
| Bare code fence | ` … ` | {code}…{code} |
| Doc link | [design](https://wiki/x) | [design|https://wiki/x] |
| Emphasis on a label | **Expected:** | *Expected:* |
QA constructs that need a manual step
Things bug reports commonly include that the transform does not handle — fix these after pasting.
| Element | What the tool does | Manual action |
|---|---|---|
| Environment matrix (GFM table) | Passes through as raw pipe text | Rebuild as ||Field||Value|| + |browser|Chrome 124| |
Screenshot  | Becomes ![shot|url] (link form, not an embed) | Drag-drop the image as a Jira attachment |
Severity/priority checkboxes - [x] | Becomes * [x] — brackets remain as text | Set Priority/Severity via Jira fields instead |
Underscored identifiers in prose (order_id) | Underscores may render as italic in Jira | Wrap in inline code so it becomes {{order_id}} |
Input limits by tier
A single large log paste can exceed the Free character cap before the file-size cap.
| Tier | Max size | Max characters | Files / run |
|---|---|---|---|
| Free | 1 MB | 500,000 | 1 |
| Pro | 10 MB | 5,000,000 | 1 used |
| Pro + Media | 50 MB | 20,000,000 | 1 used |
| Developer | 500 MB | Unlimited | 1 used |
Cookbook
Real bug-report fragments before and after conversion. PII and hostnames anonymized.
Expected / Actual block with bold labels
Bold labels collapse to single asterisks, and the heading becomes h3. This is the core of most bug reports.
Markdown in: ### Expected vs Actual **Expected:** Redirect to /dashboard. **Actual:** 500 error. Jira out: h3. Expected vs Actual *Expected:* Redirect to /dashboard. *Actual:* 500 error.
Numbered reproduction steps with a nested detail
Top-level steps become #; a two-space-indented sub-step becomes ##. Numbering is regenerated by Jira's renderer.
Markdown in: 1. Open the login page 2. Submit empty credentials 1. Observe the network tab 3. Page returns 500 Jira out: # Open the login page # Submit empty credentials ## Observe the network tab # Page returns 500
Stack trace in a fenced block
The trace is stashed before inline rules run, so the asterisks in the pointer arithmetic and the brackets in the array index are preserved verbatim.
Markdown in:
```text
TypeError: cannot read x[0]
at handler (app.js:42)
at *internal* dispatch
```
Jira out:
{code:text}
TypeError: cannot read x[0]
at handler (app.js:42)
at *internal* dispatch
{code}Environment details as a bullet list (not a table)
When you want the environment info to convert cleanly, use a bullet list rather than a GFM table — bullets become * items, tables do not convert.
Markdown in: - OS: Windows 11 - Browser: Chrome 124 - Build: 2026.6.1 Jira out: * OS: Windows 11 * Browser: Chrome 124 * Build: 2026.6.1
Inline command and a repo link in one step
Inline code becomes the {{…}} macro and the link flips to pipe form — both in the same line.
Markdown in:
Run `make test` against the [feature branch](https://git/pr/88).
Jira out:
Run {{make test}} against the [feature branch|https://git/pr/88].Edge cases and what actually happens
Environment matrix table stays plain text
By designA GFM environment table is not converted — it renders as monospaced plain text in Jira. Either rebuild it as ||Field||Value|| rows after pasting, or write the environment details as a bullet list in your source so they convert to * items cleanly.
Screenshots are not embedded
Manual fix becomes ![screenshot|url], which Jira will not render as an image. Attach screenshots directly to the ticket via drag-drop — attachments are more reliable than external image URLs and survive even if the source URL rotates.
Stack trace with backticks inside it
PreservedBecause the whole fenced block is stashed before inline rules run, backticks, asterisks, underscores, and brackets inside a stack trace are preserved exactly. You do not need to escape anything inside the fence.
Lazy blockquote for an actual-output note
Watch outIf you quote observed output with > on only the first line and rely on lazy continuation, only that first line becomes bq.. Add > to every quoted line, or put multi-line output in a code fence instead so it becomes a {code} block.
Severity checkbox brackets remain
Manual fixA - [ ] Blocker line becomes * [ ] Blocker — only the bullet is rewritten. Jira wiki has no native checkbox, so set severity/priority through Jira fields rather than inline brackets.
Underscored identifiers render as italic
Watch outAn error mentioning customer_ref in prose can render the middle as italic in Jira because _ means italic. Wrap such identifiers in inline code in your source so they become {{customer_ref}} monospace, which is safe.
Pasted into rich-text editor
Display issuePasting wiki markup into Jira's WYSIWYG description shows literal h2. and # characters. Switch the Description field to wiki / text mode before pasting, then toggle back to verify the repro steps numbered correctly.
Empty report
ExpectedRunning with no input returns an empty string. Paste the report or pick a file before clicking Run.
Huge log paste exceeds Free char limit
Tier limitA full debug log can blow past the Free 500,000-character cap even under 1 MB. Trim the log to the relevant frames, or upgrade to Pro (5,000,000 characters). Keep traces in a code fence so they convert to a single {code} block.
Frequently asked questions
Will my stack traces render in monospace?
Yes, if they are inside a fenced code block (``` ). A text fence becomes {code:text}…{code} and a bare fence becomes {code}…{code}`. Everything inside is preserved exactly — no characters in the trace are reinterpreted as formatting.
How do I add screenshots to the bug ticket?
Attach them directly to the Jira ticket via drag-drop after pasting. The converter does not embed images —  comes out as ![alt|url], a link form Jira will not render as an image. Jira attachments are the reliable path for QA screenshots.
Do numbered repro steps stay numbered?
Yes. 1., 2., 3. each become #, which is Jira's ordered-list marker. Jira's renderer regenerates the visible numbers. Two-space-indented sub-steps gain an extra # per level (##, ###).
Does the environment table convert?
No. GFM tables are not handled — they pass through as plain pipe text. For environment details, either write them as a bullet list (which converts to * items) or rebuild the table in Jira as ||Field||Value||. If you need to fix a malformed source table first, try md-table-repair.
How do nested repro steps map?
Indentation is read as two spaces per level. A two-space-indented 1. becomes ##; a four-space indent becomes ###. If your editor uses tabs or four-space indents, normalize to two-space indents first — md-prettifier can do that.
Can I include severity or priority as checkboxes?
Checkbox markers like - [ ] survive only as * [ ] text — Jira wiki has no native checkbox. Set severity and priority using Jira's issue fields when you create the ticket instead of inline brackets.
Are there options to control the output?
No. The transform is deterministic with no configurable options. To shape the result, edit the Markdown source before converting. Sibling cleaners like md-lint and md-bold-italic-cleaner help normalize the source first.
Will internal hostnames or tokens be uploaded?
No. The conversion runs entirely in your browser. Repro steps containing internal URLs, tokens, or customer identifiers never reach a server. Only an anonymous run counter is recorded for dashboard stats.
What format is the output and how do I save it?
Plain text. Use Copy for the clipboard or Download for a -jira.txt file (original filename plus -jira.txt). Paste the copied text into the Jira Description field in wiki / text mode.
How large a report can I convert?
Free tier: 1 MB / 500,000 characters in one file. Pro: 10 MB / 5,000,000 characters. The character cap is checked separately from byte size, so a dense log can hit it first. This tool processes one report at a time.
What if the repro uses underscores in code identifiers?
Wrap them in inline code. In prose, order_id can render as italic because Jira treats _ as emphasis. Writing ` order_id makes it {{order_id}}` monospace, which renders literally and avoids accidental italics.
Where do I go for a non-Jira bug-ticket target?
For Slack-thread triage formatting see md-to-slack; for a Confluence test-report page see the Confluence page guide; for a Word doc of the report see md-to-docx.
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.