# Jarkdown - Export Jira Issues to Markdown
[](https://jarkdown.readthedocs.io/en/latest/?badge=latest)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/chrisbyboston/jarkdown/actions)
[](https://github.com/chrisbyboston/jarkdown/actions)
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](https://jarkdown.readthedocs.io/), including:
- [Getting Started for Beginners](https://jarkdown.readthedocs.io/en/latest/beginners_guide.html) - Step-by-step guide for new users
- [AI-Powered Development](https://jarkdown.readthedocs.io/en/latest/use_case_ai_context.html) - A guide on the "vibecoding" workflow
- [Installation Guide](https://jarkdown.readthedocs.io/en/latest/installation.html)
- [Usage Guide](https://jarkdown.readthedocs.io/en/latest/usage.html)
- [Configuration](https://jarkdown.readthedocs.io/en/latest/configuration.html)
- [Contributing](https://jarkdown.readthedocs.io/en/latest/contributing.html)
## 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:
```bash
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=your-email@example.com
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:
```bash
git clone https://github.com/chrisbyboston/jarkdown.git
cd jarkdown
```
2. Create a virtual environment and install dependencies:
**On macOS/Linux:**
```bash
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
```
**On Windows:**
```bash
python -m venv venv
venv\Scripts\activate
pip install -e ".[dev]"
```
3. Set up your `.env` file as described above
## Usage
Basic usage:
```bash
jarkdown ISSUE-KEY
```
Examples:
```bash
# 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:
```bash
git clone https://github.com/YOUR-USERNAME/jarkdown.git
cd jarkdown
```
2. **Create a virtual environment** and install dependencies:
```bash
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
```
3. **Install pre-commit hooks**:
```bash
pre-commit install
```
### Making Changes
1. **Create a feature branch**:
```bash
git checkout -b feature/your-feature-name
```
2. **Make your changes** and ensure tests pass:
```bash
pytest
pytest --cov=src/jarkdown --cov-report=term-missing
```
3. **Commit your changes** (pre-commit hooks will run automatically):
```bash
git add .
git commit -m "feat: describe your change"
```
4. **Push and create a pull request**:
```bash
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:
```bash
# 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](https://github.com/chrisbyboston/jarkdown/issues) to report bugs or request features.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "jarkdown",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Chris Reynolds <chrisbyboston@gmail.com>",
"keywords": "jira, markdown, export, documentation, atlassian, issue-tracker",
"author": null,
"author_email": "Chris Reynolds <chrisbyboston@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/68/ff/c38a7a14e1737dffaac32206f717e2df4be534e0bb7e079fa5e6902ee072/jarkdown-0.1.0.tar.gz",
"platform": null,
"description": "# Jarkdown - Export Jira Issues to Markdown\n\n[](https://jarkdown.readthedocs.io/en/latest/?badge=latest)\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://github.com/chrisbyboston/jarkdown/actions)\n[](https://github.com/chrisbyboston/jarkdown/actions)\n\nA command-line tool that exports Jira Cloud issues into clean, portable Markdown files, optimized for AI-powered development workflows.\n\nJarkdown 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.\n\n## Primary Use Case: Context for AI Coding Assistants (\"Vibecoding\")\n\nA primary use case for Jarkdown is to provide rich, accurate context to AI-powered coding assistants (like GitHub Copilot, Gemini, Claude, etc.).\n\nThe main challenge when using AI for a development task is its lack of access to the context inside a Jira ticket\u2014the 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.\n\nThis 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.\n\n## Documentation\n\nFull documentation is available at [jarkdown.readthedocs.io](https://jarkdown.readthedocs.io/), including:\n\n- [Getting Started for Beginners](https://jarkdown.readthedocs.io/en/latest/beginners_guide.html) - Step-by-step guide for new users\n- [AI-Powered Development](https://jarkdown.readthedocs.io/en/latest/use_case_ai_context.html) - A guide on the \"vibecoding\" workflow\n- [Installation Guide](https://jarkdown.readthedocs.io/en/latest/installation.html)\n- [Usage Guide](https://jarkdown.readthedocs.io/en/latest/usage.html)\n- [Configuration](https://jarkdown.readthedocs.io/en/latest/configuration.html)\n- [Contributing](https://jarkdown.readthedocs.io/en/latest/contributing.html)\n\n## Key Features\n\n- **AI-Ready Exports:** Generates clean, portable Markdown perfect for AI prompts.\n- **Complete Context:** Fetches issue descriptions, metadata, and downloads all attachments locally.\n- **Preserves Formatting:** Converts Jira's HTML to GitHub-flavored Markdown, keeping headings, lists, code blocks, and tables intact.\n- **Embeds Local Links:** Automatically references downloaded attachments with local links in the Markdown file.\n- **Simple and Fast:** A command-line tool that is easy to script and integrate into your workflow.\n\n## Installation\n\n### Quick Install (Recommended)\n\nInstall directly from PyPI with a single command:\n```bash\npip install jarkdown\n```\n\n### Configuration\n\nAfter installation, you need to set up your Jira credentials. Create a file named `.env` in the directory where you'll run the `jarkdown` command:\n\n1. Create the `.env` file with the following content:\n```\nJIRA_DOMAIN=your-company.atlassian.net\nJIRA_EMAIL=your-email@example.com\nJIRA_API_TOKEN=your-api-token-here\n```\n\n2. Replace the values with your actual Jira information:\n - `JIRA_DOMAIN`: Your Atlassian domain (e.g., company.atlassian.net)\n - `JIRA_EMAIL`: The email address you use to log into Jira\n - `JIRA_API_TOKEN`: Your personal API token (see below)\n\n### Getting Your Jira API Token\n\n1. Go to https://id.atlassian.com/manage-profile/security/api-tokens\n2. Click \"Create API token\"\n3. Give it a name (e.g., \"jarkdown\")\n4. Copy the token and paste it into your `.env` file\n\n### For Developers (Installing from Source)\n\nIf you want to contribute to the project or need the latest development version:\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/chrisbyboston/jarkdown.git\ncd jarkdown\n```\n\n2. Create a virtual environment and install dependencies:\n\n**On macOS/Linux:**\n```bash\npython3 -m venv venv\nsource venv/bin/activate\npip install -e \".[dev]\"\n```\n\n**On Windows:**\n```bash\npython -m venv venv\nvenv\\Scripts\\activate\npip install -e \".[dev]\"\n```\n\n3. Set up your `.env` file as described above\n\n## Usage\n\nBasic usage:\n```bash\njarkdown ISSUE-KEY\n```\n\nExamples:\n```bash\n# Download an issue to the current directory\njarkdown PROJ-123\n\n# Download to a specific directory\njarkdown PROJ-123 --output ~/Documents/jira-exports\n\n# Enable verbose logging\njarkdown PROJ-123 --verbose\n\n# Show version\njarkdown --version\n```\n\n## Output Structure\n\nThe tool creates a directory named after the issue key containing:\n- A markdown file with the issue content\n- All attachments downloaded from the issue\n\nExample:\n```\nPROJ-123/\n\u251c\u2500\u2500 PROJ-123.md # Issue content in markdown\n\u251c\u2500\u2500 diagram.png # Downloaded attachments\n\u251c\u2500\u2500 report.pdf\n\u2514\u2500\u2500 ...\n```\n\n## Markdown Format\n\nThe generated markdown includes:\n- Issue title with link to Jira\n- Metadata (Type, Status, Priority, Assignee, Reporter)\n- Description with preserved formatting\n- Attachments section with all files\n\nImages are embedded inline, other files are linked.\n\n## Requirements\n\n- Python 3.8+\n- Jira Cloud instance\n- Jira API token with read permissions\n\n## Dependencies\n\n- `requests` - HTTP client for API calls\n- `markdownify` - HTML to Markdown conversion\n- `python-dotenv` - Environment variable management\n\n## Limitations\n\n- Currently supports single issue export only\n- Comments are not included (planned for future)\n- Requires Jira Cloud (not Server/Data Center)\n\n## Future Enhancements\n\n- Export multiple issues with JQL queries\n- Include issue comments\n- Support for bulk export\n- Hierarchical export (epics with stories)\n- Better ADF format handling\n\n## Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### Development Setup\n\n1. **Fork and clone** the repository:\n```bash\ngit clone https://github.com/YOUR-USERNAME/jarkdown.git\ncd jarkdown\n```\n\n2. **Create a virtual environment** and install dependencies:\n```bash\npython3 -m venv venv\nsource venv/bin/activate\npip install -e \".[dev]\"\n```\n\n3. **Install pre-commit hooks**:\n```bash\npre-commit install\n```\n\n### Making Changes\n\n1. **Create a feature branch**:\n```bash\ngit checkout -b feature/your-feature-name\n```\n\n2. **Make your changes** and ensure tests pass:\n```bash\npytest\npytest --cov=src/jarkdown --cov-report=term-missing\n```\n\n3. **Commit your changes** (pre-commit hooks will run automatically):\n```bash\ngit add .\ngit commit -m \"feat: describe your change\"\n```\n\n4. **Push and create a pull request**:\n```bash\ngit push origin feature/your-feature-name\n```\n\nThen open a pull request on GitHub.\n\n### Code Style\n\n- We use `ruff` for linting and formatting\n- Pre-commit hooks ensure code quality\n- Write clear, descriptive commit messages\n- Add tests for new functionality\n- Update documentation as needed\n\n### Testing\n\nRun the test suite:\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=src/jarkdown --cov-report=term-missing\n\n# Run specific test file\npytest tests/test_cli.py\n```\n\n### Reporting Issues\n\nPlease use the [GitHub issue tracker](https://github.com/chrisbyboston/jarkdown/issues) to report bugs or request features.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Export Jira Cloud issues to Markdown with attachments",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://jarkdown.readthedocs.io/",
"Homepage": "https://github.com/chrisbyboston/jarkdown",
"Issues": "https://github.com/chrisbyboston/jarkdown/issues",
"Repository": "https://github.com/chrisbyboston/jarkdown.git"
},
"split_keywords": [
"jira",
" markdown",
" export",
" documentation",
" atlassian",
" issue-tracker"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "605914489a3e5c0e903bd9af0eb082a2b27aec4e75b35bdfd937c8f9f7f54415",
"md5": "19b33b160189547e3e7dc0e412a1edb0",
"sha256": "cda00c163a84d3b42e92e89fda710c26da1fec5513d834bb2c62b61abbf18028"
},
"downloads": -1,
"filename": "jarkdown-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "19b33b160189547e3e7dc0e412a1edb0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15882,
"upload_time": "2025-08-16T20:44:01",
"upload_time_iso_8601": "2025-08-16T20:44:01.612118Z",
"url": "https://files.pythonhosted.org/packages/60/59/14489a3e5c0e903bd9af0eb082a2b27aec4e75b35bdfd937c8f9f7f54415/jarkdown-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "68ffc38a7a14e1737dffaac32206f717e2df4be534e0bb7e079fa5e6902ee072",
"md5": "15fd3adefb81198f47579e1d34d278a9",
"sha256": "9bc996fd978f58a20a0aa9f8c87e36d5e9699fb9a3cf7895831c58af53a44dfe"
},
"downloads": -1,
"filename": "jarkdown-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "15fd3adefb81198f47579e1d34d278a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18451,
"upload_time": "2025-08-16T20:44:03",
"upload_time_iso_8601": "2025-08-16T20:44:03.267240Z",
"url": "https://files.pythonhosted.org/packages/68/ff/c38a7a14e1737dffaac32206f717e2df4be534e0bb7e079fa5e6902ee072/jarkdown-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 20:44:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chrisbyboston",
"github_project": "jarkdown",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jarkdown"
}
JSON
