jarkdown 0.1.0

Export Jira Cloud issues to Markdown with attachments

Jarkdown - Export Jira Issues to Markdown

A command-line tool that exports Jira Cloud issues into clean, portable Markdown files, optimized for AI-powered development workflows.

Jarkdown is designed to bridge the gap between Jira and your local environment. It makes it easy to archive tickets, share them with others, or provide deep, accurate context to AI coding assistants, ensuring they understand the full "vibe" of a task.

Primary Use Case: Context for AI Coding Assistants ("Vibecoding")

A primary use case for Jarkdown is to provide rich, accurate context to AI-powered coding assistants (like GitHub Copilot, Gemini, Claude, etc.).

The main challenge when using AI for a development task is its lack of access to the context inside a Jira ticket—the requirements, discussions, attachments, and metadata. Jarkdown solves this by exporting the entire issue into a clean, self-contained Markdown file with all attachments downloaded locally and referenced.

This file can be easily included in a prompt, giving the assistant all the necessary information to generate highly relevant and accurate code. This workflow, sometimes referred to as "vibecoding," ensures the AI understands the complete scope and nuance of the task, leading to significantly better results and faster development cycles.

Documentation

Full documentation is available at jarkdown.readthedocs.io, including:

• Getting Started for Beginners - Step-by-step guide for new users
• AI-Powered Development - A guide on the "vibecoding" workflow
• Installation Guide
• Usage Guide
• Configuration
• Contributing

Key Features

• AI-Ready Exports: Generates clean, portable Markdown perfect for AI prompts.
• Complete Context: Fetches issue descriptions, metadata, and downloads all attachments locally.
• Preserves Formatting: Converts Jira's HTML to GitHub-flavored Markdown, keeping headings, lists, code blocks, and tables intact.
• Embeds Local Links: Automatically references downloaded attachments with local links in the Markdown file.
• Simple and Fast: A command-line tool that is easy to script and integrate into your workflow.

Installation

Quick Install (Recommended)

Install directly from PyPI with a single command:

pip install jarkdown

Configuration

After installation, you need to set up your Jira credentials. Create a file named .env in the directory where you'll run the jarkdown command:

1. Create the .env file with the following content:

JIRA_DOMAIN=your-company.atlassian.net
JIRA_EMAIL=[e-mail]
JIRA_API_TOKEN=your-api-token-here

2. Replace the values with your actual Jira information:
   • JIRA_DOMAIN: Your Atlassian domain (e.g., company.atlassian.net)
   • JIRA_EMAIL: The email address you use to log into Jira
   • JIRA_API_TOKEN: Your personal API token (see below)

Getting Your Jira API Token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give it a name (e.g., "jarkdown")
4. Copy the token and paste it into your .env file

For Developers (Installing from Source)

If you want to contribute to the project or need the latest development version:

1. Clone the repository:

git clone https://github.com/chrisbyboston/jarkdown.git
cd jarkdown

2. Create a virtual environment and install dependencies:

On macOS/Linux:

python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

On Windows:

python -m venv venv
venv\Scripts\activate
pip install -e ".[dev]"

3. Set up your .env file as described above

Usage

Basic usage:

jarkdown ISSUE-KEY

Examples:

# Download an issue to the current directory
jarkdown PROJ-123

# Download to a specific directory
jarkdown PROJ-123 --output ~/Documents/jira-exports

# Enable verbose logging
jarkdown PROJ-123 --verbose

# Show version
jarkdown --version

Output Structure

The tool creates a directory named after the issue key containing:

• A markdown file with the issue content
• All attachments downloaded from the issue

Example:

PROJ-123/
├── PROJ-123.md       # Issue content in markdown
├── diagram.png       # Downloaded attachments
├── report.pdf
└── ...

Markdown Format

The generated markdown includes:

• Issue title with link to Jira
• Metadata (Type, Status, Priority, Assignee, Reporter)
• Description with preserved formatting
• Attachments section with all files

Images are embedded inline, other files are linked.

Requirements

• Python 3.8+
• Jira Cloud instance
• Jira API token with read permissions

Dependencies

• requests - HTTP client for API calls
• markdownify - HTML to Markdown conversion
• python-dotenv - Environment variable management

Limitations

• Currently supports single issue export only
• Comments are not included (planned for future)
• Requires Jira Cloud (not Server/Data Center)

Future Enhancements

• Export multiple issues with JQL queries
• Include issue comments
• Support for bulk export
• Hierarchical export (epics with stories)
• Better ADF format handling

Contributing

We welcome contributions! Here's how to get started:

Development Setup

1. Fork and clone the repository:

git clone https://github.com/YOUR-USERNAME/jarkdown.git
cd jarkdown

2. Create a virtual environment and install dependencies:

python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

3. Install pre-commit hooks:

pre-commit install

Making Changes

1. Create a feature branch:

git checkout -b feature/your-feature-name

2. Make your changes and ensure tests pass:

pytest
pytest --cov=src/jarkdown --cov-report=term-missing

3. Commit your changes (pre-commit hooks will run automatically):

git add .
git commit -m "feat: describe your change"

4. Push and create a pull request:

git push origin feature/your-feature-name

Then open a pull request on GitHub.

Code Style

• We use ruff for linting and formatting
• Pre-commit hooks ensure code quality
• Write clear, descriptive commit messages
• Add tests for new functionality
• Update documentation as needed

Testing

Run the test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=src/jarkdown --cov-report=term-missing

# Run specific test file
pytest tests/test_cli.py

Reporting Issues

Please use the GitHub issue tracker to report bugs or request features.

License

This project is licensed under the MIT License - see the LICENSE file for details.