Skip to content

chatgpt_to_markdown

The top-level package exposes the main CLI entry point and the orchestration class.

main()

def main() -> None

CLI entry point. Invokes the Cyclopts app defined in cli.py. Called by the chatgpt-to-markdown console script when run from the command line.

ChatGPTExportConverter

class ChatGPTExportConverter:
    def __init__(self, config: ConverterConfig) -> None: ...
    def run(self) -> None: ...

Orchestrates the full 11-step export-to-Markdown conversion pipeline.

Constructor

Parameters:

  • config (ConverterConfig) — converter configuration

run()

Executes the full pipeline in sequence:

  1. Loads export_manifest.json, user.json, user_settings.json, message_feedback.json
  2. Builds a file_id → Path lookup index from the manifest
  3. Parses all conversations-*.json partitions into validated Pydantic models
  4. Builds a feedback lookup index keyed by conversation ID
  5. Resolves file-service:// and sediment:// asset pointers to local paths
  6. Linearises message DAGs from current_node to the root node
  7. Filters messages by visibility rules (weight, hidden flags, include_thinking)
  8. Renders conversations to Markdown via Jinja2 templates
  9. Organises media and attachments with SHA-256 content-addressed naming
  10. Generates index.md files at each directory level
  11. Validates output integrity and logs broken links and missing assets

Returns: None

Side effects: Writes the full archive to config.output_dir. Logs progress at each step using the root logger.

Error handling: Per-conversation exceptions are caught, logged, and skipped. The pipeline continues with remaining conversations rather than aborting.

Usage

from pathlib import Path

from chatgpt_to_markdown.config import ConverterConfig
from chatgpt_to_markdown.converter import ChatGPTExportConverter

config = ConverterConfig(
    input_dir=Path("./my-export"),
    output_dir=Path("./archive"),
    redact_pii=True,
    include_thinking=False,
)

converter = ChatGPTExportConverter(config)
converter.run()

ConverterConfig

from chatgpt_to_markdown.config import ConverterConfig

ConverterConfig extends pydantic_settings.BaseSettings and reads values from CLI flags, environment variables, and .env files using the CONVERTER_ prefix.

See the configuration reference for full field documentation.