Getting Started for Beginners

Welcome! This guide will walk you through setting up and using Jarkdown, even if you’re new to command-line tools. We’ll explain everything step by step.

What is Jarkdown?

Jarkdown is a tool that helps you export issues from Jira (a project management system) into Markdown files on your computer. This is useful for:

  • Creating offline documentation

  • Sharing issues with people who don’t have Jira access

  • Archiving completed projects

  • Including Jira content in other documents

Prerequisites

Before you begin, you’ll need:

  1. Python installed on your computer - Jarkdown requires Python 3.8 or newer

  2. A Jira Cloud account - You need access to a Jira instance

  3. A Jira API token - We’ll show you how to get this

Step 1: Install Python

If you don’t have Python installed:

On Windows:

  1. Go to python.org/downloads

  2. Download the latest Python 3 version (3.8 or newer)

  3. Run the installer

  4. Important: Check the box “Add Python to PATH” during installation

  5. Click “Install Now”

On macOS:

  1. Open Terminal (find it in Applications > Utilities)

  2. Check if Python is installed by typing: python3 --version

  3. If not installed, go to python.org/downloads

  4. Download and run the macOS installer

On Linux:

Python is usually pre-installed. Open a terminal and check with: python3 --version

Step 2: Open a Terminal/Command Prompt

You’ll need to use a terminal to run Jarkdown:

On Windows:

  1. Press Windows + R

  2. Type cmd and press Enter

  3. Or search for “Command Prompt” in the Start menu

On macOS:

  1. Press Command + Space

  2. Type “Terminal” and press Enter

  3. Or find Terminal in Applications > Utilities

On Linux:

  • Press Ctrl + Alt + T on most distributions

  • Or look for “Terminal” in your applications menu

Step 3: Install Jarkdown

In your terminal, type this command and press Enter:

pip install jarkdown

Wait for the installation to complete. You should see messages about downloading and installing packages.

To verify the installation worked, type:

jarkdown --version

You should see the version number displayed.

Step 4: Get Your Jira API Token

  1. Open your web browser and go to: https://id.atlassian.com/manage-profile/security/api-tokens

  2. Log in with your Atlassian account (the same one you use for Jira)

  3. Click the blue “Create API token” button

  4. Give your token a name like “jarkdown”

  5. Click “Create”

  6. Important: Copy the token that appears - you won’t be able to see it again!

  7. Save it somewhere safe (like a password manager or secure note)

Step 5: Configure Jarkdown

You need to tell Jarkdown how to connect to your Jira instance.

Creating the Configuration File

  1. In your terminal, navigate to where you want to work with Jira issues. For example:

    • Windows: cd C:\Users\YourName\Documents

    • Mac/Linux: cd ~/Documents

  2. Create a new file called .env (note the dot at the beginning!)

On Windows (using Notepad):

notepad .env

On macOS/Linux (using nano):

nano .env

  1. In the file, add these three lines (replace with your actual information):

JIRA_DOMAIN=yourcompany.atlassian.net
JIRA_EMAIL=your.email@example.com
JIRA_API_TOKEN=paste-your-token-here

Where:

  • JIRA_DOMAIN: The web address you use to access Jira (without https://)

  • JIRA_EMAIL: The email you use to log into Jira

  • JIRA_API_TOKEN: The token you created in Step 4

  1. Save the file:

    • In Notepad: File > Save

    • In nano: Press Ctrl+X, then Y, then Enter

Step 6: Use Jarkdown

Now you’re ready to export your first Jira issue!

Basic Usage

To export a Jira issue, you need its key (like “PROJ-123”). In your terminal, type:

jarkdown PROJ-123

Replace “PROJ-123” with your actual issue key.

This will:

  1. Connect to Jira and fetch the issue

  2. Download any attachments

  3. Create a folder named after the issue

  4. Save everything as markdown files

Where Are My Files?

Jarkdown creates a new folder in your current directory. For example, if you run jarkdown PROJ-123, it creates:

PROJ-123/
├── PROJ-123.md       (the issue content)
├── image1.png        (any attachments)
├── document.pdf
└── ...

Specifying an Output Directory

To save files in a specific location:

jarkdown PROJ-123 --output C:\Users\YourName\Desktop\JiraExports

Or on Mac/Linux:

jarkdown PROJ-123 --output ~/Desktop/JiraExports

Troubleshooting

“Command not found” error

  • Make sure Python and pip are installed correctly

  • On Windows, you may need to restart your terminal after installing Python

  • Try python -m pip install jarkdown instead

“Authentication failed” error

  • Double-check your API token is correct

  • Verify your email address is the one you use for Jira

  • Make sure your .env file is in the current directory

“Issue not found” error

  • Check that the issue key is correct (including the project prefix)

  • Verify you have permission to view the issue in Jira

Can’t see the .env file

Files starting with a dot are hidden by default:

  • Windows: In File Explorer, click View > Show > Hidden items

  • macOS: In Finder, press Command + Shift + .

  • Linux: In your file manager, press Ctrl + H

Getting Help

If you encounter issues:

  1. Check the error message for clues

  2. Visit the documentation

  3. Report issues at GitHub

Next Steps

Once you’re comfortable with basic usage, explore:

Congratulations! You’re now ready to export Jira issues to markdown.