Metadata-Version: 2.4
Name: chatgpt-to-markdown
Version: 0.1.0
Summary: A tool to convert ChatGPT export files into Markdown format.
Keywords: chatgpt,markdown,export,converter,cli,openai,archive,documentation
Author: Diego Gamboa
Author-email: Diego Gamboa <info@dgamboa.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Dist: cyclopts>=3.6.2
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: python-slugify>=8.0.0
Requires-Python: >=3.14
Project-URL: Bug Reports, https://github.com/difegam/chatgpt-to-markdown/issues
Project-URL: Documentation, https://github.com/difegam/chatgpt-to-markdown/tree/main/docs
Project-URL: Homepage, https://github.com/difegam/chatgpt-to-markdown
Project-URL: Source, https://github.com/difegam/chatgpt-to-markdown
Description-Content-Type: text/markdown

# ChatGPT to Markdown

[![CI](https://github.com/difegam/chatgpt-to-markdown/actions/workflows/ci.yml/badge.svg?event=push&branch=main)](https://github.com/difegam/chatgpt-to-markdown/actions/workflows/ci.yml?query=event%3Apush+branch%3Amain)
[![Package version](https://img.shields.io/pypi/v/chatgpt-to-markdown?color=%2334D058&label=pypi%20package)](https://pypi.org/project/chatgpt-to-markdown)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/chatgpt-to-markdown.svg?color=%2334D058)](https://pypi.org/project/chatgpt-to-markdown)
[![License](https://img.shields.io/github/license/difegam/chatgpt-to-markdown?color=%2334D058)](https://github.com/difegam/chatgpt-to-markdown/blob/main/LICENSE)

A tool-first CLI that converts ChatGPT exports into a structured, searchable, offline-friendly Markdown knowledge archive.

## Elevator Pitch

`chatgpt-to-markdown` turns your ChatGPT export into clean Markdown you can read,
index, and keep long term. Instead of browsing a raw ZIP or JSON partitions, you
get a portable archive with conversation pages, media resolution, metadata files,
and index pages, ready for local browsing, static hosting, or personal knowledge
management workflows.

---

> ## Project under active development.
>
> `chatgpt-to-markdown` is still under active development. Not all possible ChatGPT
> export variants and edge-case output structures are covered yet.
>
> Please validate the generated Markdown archive before relying on it as your only
> source of truth, and **please report issues** (with repro details when possible) so we can
> make the tool more robust and feature-complete.
>
> For safety and recoverability, keep your original ChatGPT export ZIP stored
> securely. As issues are fixed, you can regenerate the output from that source to
> pick up improvements.

---

## Features

- Parses all `conversations-*.json` partitions with Pydantic v2 validation
- Walks message DAGs to linearise conversation threads (handles branches and cycles)
- Resolves `file-service://` and `sediment://` asset pointers against the export manifest
- Renders conversations to Markdown with YAML front matter via Jinja2 templates
- Generates index files for conversations, DALL-E generations, and metadata
- Deduplicates media by SHA-256 hash
- Supports 12+ content types with a fallback for unknown types
- Optional PII redaction for user metadata
- Optional inclusion of thinking/reasoning blocks from o-series models
- Accepts both extracted directories and ZIP files as input

## Installation

### Run without installing

```bash
uvx chatgpt-to-markdown --help
```

Convert a ChatGPT export ZIP or extracted directory to a Markdown archive:

```bash
# From ZIP file
uvx chatgpt-to-markdown ./chatgpt-export.zip ./archive_zip

# From extracted directory
uvx chatgpt-to-markdown ./chatgpt-export ./archive
```

### Install as a global CLI tool with uv (recommended for frequent use)

```bash
uv tool install chatgpt-to-markdown
```

### Development install (contributors)

```bash
git clone https://github.com/difegam/chatgpt-to-markdown.git
cd chatgpt-to-markdown
uv sync --all-groups
```

## Usage

```bash
# Run without installing (ephemeral env)
uvx chatgpt-to-markdown ./chatgpt-export.zip ./archive

# Or use the installed global CLI
chatgpt-to-markdown ./chatgpt-export.zip ./archive

# Convert an extracted export directory
uvx chatgpt-to-markdown ./my-export ./archive

# Convert a ZIP file directly
uvx chatgpt-to-markdown ./chatgpt-export.zip ./archive

# With options
uvx chatgpt-to-markdown ./my-export ./archive --no-redact-pii --include-thinking

# From a local repository checkout (contributors)
uv run chatgpt-to-markdown ./my-export ./archive
```

### CLI Options

| Option                             | Default  | Description                                            |
| ---------------------------------- | -------- | ------------------------------------------------------ |
| `input_dir`                        | required | Path to extracted ChatGPT export directory or ZIP file |
| `output_dir`                       | required | Path to output Markdown archive directory              |
| `--redact-pii / --no-redact-pii`   | `True`   | Redact PII (email, phone, birth year) in metadata      |
| `--include-thinking`               | `False`  | Include thinking/reasoning blocks from thinking models |
| `--deduplicate / --no-deduplicate` | `True`   | Deduplicate assets by SHA-256 hash                     |

## Output Structure

```text
archive/
├── index.md
├── conversations/
│   ├── index.md
│   └── 2024-08-24_test-chat_17cd7535/
│       ├── index.md
│       ├── media/
│       │   └── 001-a1b2c3d4.jpeg
│       └── attachments/
│           └── document.pdf
├── dalle/
│   ├── index.md
│   └── *.webp
└── metadata/
    ├── user_profile.md
    ├── settings.md
    ├── feedback.md
    └── export_stats.md
```

## Development

```bash
just init    # Install dependencies and pre-commit hooks
just test    # Run tests
just check   # Run all quality checks
just docs    # Serve docs locally
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and the [documentation](docs/) for full development guides.

## Publishing

This repository includes `.github/workflows/publish.yml` for PyPI trusted publishing with `uv`.

Reference: [Building and publishing a package using uv](https://docs.astral.sh/uv/guides/package/)

1. Create the `pypi` environment in GitHub: `Settings → Environments → New environment`.

1. In PyPI, add a Trusted Publisher for this project with:

    - Owner: `difegam`
    - Repository: `chatgpt-to-markdown`
    - Workflow: `publish.yml`
    - Environment: `pypi`

1. Create and push a version tag:

    ```bash
    git tag -a v0.1.0 -m "v0.1.0"
    git push --tags
    ```

1. The `Publish` workflow runs and executes `uv build` and `uv publish`.
