markdown2jira

Markdown to Jira CSV Import Guide

Turn a Markdown outline into a Jira CSV import file and bulk-create Epics, Stories, Tasks and Sub-tasks in one go. Skip the manual work with the free Markdown to Jira converter →

Step-by-step

  1. 1

    Write your backlog in Markdown

    Use headings and lists to describe your work. H1 becomes an Epic, H2 a Story, H3 a Task; top-level bullets become Tasks and nested bullets become Sub-tasks.

  2. 2

    Convert to a Jira CSV file

    Paste the Markdown into the converter, open the CSV tab, review the issue-type mapping, and download the generated CSV.

  3. 3

    Open Jira's CSV importer

    In Jira, go to Settings → System → External System Import → CSV, or use the project-level 'Import issues from CSV' option.

  4. 4

    Upload and map columns

    Upload the CSV, then map the Summary, Issue Type, Epic Link and Parent ID columns to the matching Jira fields. Jira previews the issues before creating them.

  5. 5

    Run the import

    Confirm the mapping and run the import. Jira bulk-creates every row as an Epic, Story, Task or Sub-task with the parent links preserved.

How Markdown maps to Jira issue types

Markdown Jira issue type Notes
# H1 Epic Top-level initiative
## H2 Story Belongs to the Epic above
### H3 Task Belongs to the Story above
- bullet Task Top-level list item
- nested bullet Sub-task Child of the item above

Example CSV output

Issue ID,Issue Type,Summary,Epic Name,Epic Link,Parent ID
1,Epic,Checkout revamp,Checkout revamp,,
2,Story,Payment page,,Checkout revamp,
3,Sub-task,Add Apple Pay,,,2

Frequently asked questions

Can I import Markdown into Jira directly?

Jira does not accept Markdown files directly, but it does import CSV. This tool converts your Markdown into a Jira-ready CSV so you can bulk-create issues in one step.

How are Epics, Stories, Tasks and Sub-tasks decided?

By default H1 → Epic, H2 → Story, H3 → Task, top-level bullets → Task and nested bullets → Sub-task. You can change this mapping in the CSV tab before downloading.

Does the CSV keep parent-child relationships?

Yes. Stories link to their Epic through the Epic Link column, and Sub-tasks link to their parent through the Parent ID column, so Jira rebuilds the full hierarchy on import.

Is my data uploaded anywhere?

No. The conversion runs entirely in your browser — your Markdown and the generated CSV never leave your device.

Ready to bulk-import?

Paste your Markdown, download a Jira-ready CSV, and import in minutes.

Open the Markdown to Jira converter