How to format feature requests for jira issues
- Step 1Paste or upload the feature request — Use Paste text for a quick brief or Upload file for a
.mdspec. Single file only — combine multiple drafts with md-merger first if needed. - Step 2Click Run — The converter stashes any fenced code, then rewrites headings, story lists, acceptance-criteria items, links, and emphasis. No options to set.
- Step 3Check the story structure — Confirm Context / Goals / Non-goals became
h2.headings and that the user-story bullets became a clean*list. - Step 4Review acceptance criteria — If you used plain bullets, they converted to
*items. If you used- [ ]checkboxes, the brackets remain as text — decide whether to strip them or model them as Jira sub-tasks. - Step 5Copy and create the Jira issue — Click Copy, then in the new-issue dialog switch the Description to wiki / text mode and paste. Toggle to the rendered view to verify.
- Step 6Add epic links, labels, and matrices in Jira — Set the Epic Link and labels via Jira fields (text like
EPIC-123auto-links once saved). Rebuild any scope/priority table as||header||rows by hand.
Feature-request elements and their Jira output
How the parts of a typical product brief map through the transform.
| Spec element | Markdown | Jira output |
|---|---|---|
| Section heading | ## Context | h2. Context |
| Sub-section | ### User Story | h3. User Story |
| Story bullet | - As a PM, I want… | * As a PM, I want… |
| Acceptance item (plain) | - Login persists 30 days | * Login persists 30 days |
| Acceptance item (checkbox) | - [ ] Email is sent | * [ ] Email is sent |
| Numbered milestone | 1. MVP | # MVP |
| Design link | [Figma](https://figma/x) | [Figma|https://figma/x] |
| Bold label | **Priority:** | *Priority:* |
| Inline flag name | dark_mode | {{dark_mode}} |
PM constructs that need a manual step
Things product briefs include that the transform does not handle.
| Element | What the tool does | Manual action |
|---|---|---|
| Scope / priority matrix (GFM table) | Passes through as raw pipe text | Rebuild as ||Feature||Priority|| or use Jira fields |
Acceptance-criteria checkboxes - [ ] | Becomes * [ ] — brackets stay as text | Strip brackets or split into Jira sub-tasks |
Epic link EPIC-123 | Passes through as plain text | Set the Epic Link field; Jira auto-links the key |
Embedded Figma preview  | Becomes ![flow|url] (link form) | Use Jira's Figma integration or attach the export |
Input limits by tier
A long PRD can hit the 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
Feature-request fragments before and after conversion, written the way PMs actually draft them.
User story as a structured block
The h3 heading and the As-a/I-want/So-that bullets convert cleanly to a Jira sub-heading and list.
Markdown in: ### User Story - As a returning user - I want to stay logged in - So that I skip re-auth on each visit Jira out: h3. User Story * As a returning user * I want to stay logged in * So that I skip re-auth on each visit
Context / Goals / Non-goals headings
The three standard spec sections become h2. headings that anchor the ticket.
Markdown in: ## Context Users churn at the login wall. ## Goals Reduce repeat logins. ## Non-goals SSO is out of scope. Jira out: h2. Context Users churn at the login wall. h2. Goals Reduce repeat logins. h2. Non-goals SSO is out of scope.
Acceptance criteria with checkboxes
Checkbox bullets become * items, but the [ ] / [x] markers remain as literal text because Jira wiki has no checkbox. Decide whether to keep them as a visual marker or split into sub-tasks.
Markdown in: ## Acceptance Criteria - [ ] Session persists 30 days - [x] Logout clears the cookie Jira out: h2. Acceptance Criteria * [ ] Session persists 30 days * [x] Logout clears the cookie
Design link and a bold priority label
The Figma link flips to pipe form and the bold label collapses to a single asterisk.
Markdown in: **Priority:** P1. See the [flows](https://figma/flows). Jira out: *Priority:* P1. See the [flows|https://figma/flows].
Priority matrix left for manual rebuild
A GFM matrix passes through untouched. Rebuild as Jira table rows or move it to Jira fields.
Markdown in: | Feature | Impact | Effort | | ------- | ------ | ------ | | Login persist | high | low | Jira out (unchanged): | Feature | Impact | Effort | | ------- | ------ | ------ | | Login persist | high | low | Jira form: ||Feature||Impact||Effort|| |Login persist|high|low|
Edge cases and what actually happens
Acceptance-criteria checkboxes leave stray brackets
Manual fix- [ ] criterion becomes * [ ] criterion — only the bullet is rewritten. Jira wiki markup has no checkbox, so the [ ] / [x] text remains. Either keep them as a visual marker, strip the brackets, or split criteria into Jira sub-tasks for trackable checkboxes.
Scope / priority table not converted
By designA GFM scope or priority matrix passes through as plain pipe text. Rebuild it as ||Feature||Priority|| rows in Jira, or model the data as Jira issue fields (priority, story points) which are more actionable than a static table.
Epic and issue keys stay as plain text
PreservedReferences like EPIC-123 or PROJ-456 pass through unchanged. Jira auto-links them once the ticket is saved and the keys exist in the project. Set the formal Epic Link via the Jira field rather than relying on inline text alone.
Embedded Figma image becomes a link form
Manual fix becomes ![flow|url], which Jira will not render as an inline preview. Use Jira's Figma integration for live previews, or attach a static export of the design after creating the ticket.
Underscored flag names read as italic
Watch outA feature flag like dark_mode written in prose can render as italic in Jira (_ means italic). Wrap flag names in inline code so they become {{dark_mode}} monospace and the underscores are safe.
Story written as a paragraph, not a list
Watch outIf the As-a/I-want/So-that story is one paragraph rather than bullets, it converts as plain prose (no list markup). Write each clause as a - bullet if you want a Jira list, or keep it as a paragraph if that reads better.
Pasted into the rich-text editor
Display issueWiki markup pasted into Jira's WYSIWYG description shows literal h2. and * characters. Switch the Description to wiki / text mode before pasting, then toggle back to verify the spec structure.
Empty brief
ExpectedNo input returns an empty string. Paste the brief or select a file before clicking Run.
Long PRD exceeds Free char cap
Tier limitA full product requirements doc can pass 500,000 characters while under 1 MB. Convert section by section, or upgrade to Pro (5,000,000 characters). To assemble sections into one ticket, merge them first with md-merger.
Frequently asked questions
How should I structure acceptance criteria?
Use a ## Acceptance Criteria heading followed by a bullet list. Plain bullets convert to clean * items. If you use - [ ] checkboxes, they become * [ ] with the brackets as literal text — Jira wiki has no native checkbox, so consider splitting criteria into Jira sub-tasks for trackable progress.
Can I include Figma or design links?
Yes. A full URL like [Figma](https://figma/x) converts to [Figma|https://figma/x] and stays clickable. For inline previews, use Jira's Figma integration after creating the ticket — the converter produces a link, not an embed.
Does it support epic links?
Epic keys like EPIC-123 pass through as plain text and Jira auto-links them once the ticket is saved. For the formal relationship, set the Epic Link field in Jira rather than relying on the inline text alone.
How do user stories convert?
Write the As-a / I-want / So-that clauses as a bullet list and they become a Jira * list. If you write the story as a single paragraph, it stays as prose. Headings like ### User Story become h3. to anchor the section.
Does the scope or priority matrix convert?
No. GFM tables pass through as plain pipe text. Rebuild a matrix as ||Feature||Priority|| rows in Jira, or model it as Jira fields (priority, story points) which are more useful than a static table. Fix a broken source table first with md-table-repair if needed.
Are there options to configure the output?
No. The transform is deterministic with no settings. Shape the result by editing the Markdown. To tidy the source first, md-lint and md-prettifier help.
Will unreleased feature details be uploaded?
No. The conversion runs entirely in your browser. Unreleased feature names, revenue figures, and customer references in a brief never reach a server. Only an anonymous run counter is recorded for dashboard stats.
What output do I get and how do I save it?
Plain wiki-markup text. Use Copy for the clipboard or Download for a -jira.txt file (original name plus -jira.txt). Paste into the Jira issue Description in wiki / text mode.
How large a spec can I convert?
Free: 1 MB / 500,000 characters per file. Pro: 10 MB / 5,000,000 characters. The character cap is separate from byte size, so a dense PRD can hit it first. The tool converts one file per run; merge sections with md-merger beforehand.
How are nested goals or sub-criteria handled?
Indentation is read as two spaces per level. A two-space-indented bullet under a numbered milestone becomes ** under #. Normalize to two-space indents — md-prettifier does that — if your editor uses tabs or four-space indents.
What if my flag names have underscores?
Wrap them in inline code. In prose, feature_flag can render as italic because _ means emphasis in Jira. Writing ` feature_flag makes it {{feature_flag}}` monospace, which renders literally.
Where do I go for other handoff targets?
For a Confluence product page see the Confluence guide; for a quick Slack share of the brief see md-to-slack; for a stakeholder Word doc see md-to-docx; for an exec PDF see md-to-pdf-modern.
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.