Usage Guide

This guide covers all the ways to use jarkdown, from basic exports to advanced options.

Quick Start

The simplest usage - export a single issue:

jarkdown PROJ-123

This creates a folder named PROJ-123/ in your current directory containing:

  • PROJ-123.md - The issue content in Markdown

  • All attachments with their original filenames

Command-Line Options

Basic Syntax

jarkdown ISSUE-KEY [OPTIONS]

Available Options

--output / -o

Specify where to save the exported issue:

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

# Use short form
jarkdown PROJ-123 -o /tmp/exports

If the output directory doesn’t exist, it will be created.

--verbose / -v

Enable detailed output to see what’s happening:

jarkdown PROJ-123 --verbose

This shows:

  • API calls being made

  • Attachments being downloaded

  • File paths being created

  • Any warnings or non-critical issues

--help / -h

Display help information:

jarkdown --help

Output Structure

Each exported issue creates this structure:

PROJ-123/
├── PROJ-123.md          # Main issue content
├── screenshot.png       # Attachments keep
├── design-doc.pdf       # their original names
└── meeting-notes.docx

The Markdown File

The generated Markdown file includes:

  1. YAML Frontmatter - A block at the top of the file containing comprehensive metadata like status, priority, labels, components, parent issues, and more.

  2. Title - The issue key and summary, linked to the original Jira issue.

  3. Description - The main issue content, converted from Jira’s HTML to Markdown.

  4. Comments - All comments with author and timestamp.

  5. Attachments Section - A list of links to all downloaded attachments.

Example structure:

---
key: PROJ-123
summary: Implement user authentication
type: Story
status: In Progress
priority: High
assignee: John Smith
reporter: Jane Doe
labels:
  - auth
  - frontend
components:
  - Web App
created_at: '2024-01-15T10:30:00.000+0000'
updated_at: '2024-01-20T15:45:00.000+0000'
---

# [PROJ-123](https://your-domain.atlassian.net/browse/PROJ-123): Implement user authentication

## Description

As a user, I want to be able to log in...

![Screenshot](screenshot.png)

## Comments

**Jane Doe** - _2024-01-16 09:00 AM_

Here's the updated design: [design-doc.pdf](design-doc.pdf)

---

**John Smith** - _2024-01-17 02:30 PM_

Implementation is underway.

Common Use Cases

Archiving Completed Sprints

Export all completed issues from a sprint:

for issue in PROJ-101 PROJ-102 PROJ-103; do
    jarkdown $issue --output ~/sprints/sprint-23
done

Creating Documentation

Export issues to include in project documentation:

jarkdown EPIC-1 --output docs/requirements

Backup Before Migration

Export critical issues before system changes:

# Create timestamped backup
OUTPUT_DIR="backup-$(date +%Y%m%d)"
jarkdown CRITICAL-1 --output $OUTPUT_DIR --verbose

Offline Access

Download issues for offline work:

# Export to synced folder
jarkdown TASK-456 --output ~/Dropbox/jira-offline

Working with Attachments

Attachment Handling

  • Automatic download: All attachments are downloaded by default

  • Original names: Files keep their original names from Jira

  • Conflict resolution: Duplicate names get numbered suffixes (e.g., file-1.pdf, file-2.pdf)

  • Link updates: All references in the Markdown are updated to local paths

Large Attachments

For issues with many or large attachments:

# Use verbose to monitor progress
jarkdown PROJ-789 --verbose

The tool uses streaming downloads to handle large files efficiently.

Error Handling

Common Errors and Solutions

Issue Not Found

Error: Issue PROJ-999 not found

Solution: Verify the issue key and your access permissions

Authentication Failed

Error: Authentication failed (401)

Solution: Check your API token and email in the .env file

Network Issues

Error: Connection timeout

Solution: Check your internet connection and Jira availability

Retry Failed Downloads

If a download fails partway through:

# Remove partial download
rm -rf PROJ-123/

# Retry with verbose output
jarkdown PROJ-123 --verbose

Advanced Usage

Scripting and Automation

Use jarkdown in scripts:

#!/usr/bin/env python3
import subprocess
import os

issues = ['PROJ-1', 'PROJ-2', 'PROJ-3']
output_base = '/path/to/exports'

for issue in issues:
    result = subprocess.run(
        ['jarkdown', issue, '--output', output_base],
        capture_output=True,
        text=True
    )
    if result.returncode == 0:
        print(f"✓ Exported {issue}")
    else:
        print(f"✗ Failed to export {issue}: {result.stderr}")

Integration with Other Tools

Process exported Markdown with other tools:

# Export and convert to HTML
jarkdown PROJ-123
pandoc PROJ-123/PROJ-123.md -o PROJ-123.html

# Export and create PDF
jarkdown PROJ-456
pandoc PROJ-456/PROJ-456.md -o PROJ-456.pdf --pdf-engine=xelatex

Tips and Best Practices

  1. Regular Backups: Schedule regular exports of important issues

  2. Organize by Project: Use --output to organize exports by project or sprint

  3. Version Control: Consider committing exported issues to Git for history

  4. Clean URLs: The tool handles various Jira URL formats for attachments

  5. Batch Operations: Use shell scripts for bulk exports

Next Steps