deepseek-json-to-markdown-converter 0.1.0

Convert DeepSeek conversations.json exports to markdown files

DeepSeek JSON to Markdown Converter

Tool for converting DeepSeek chat export JSON files (conversations.json) into high-fidelity Markdown files suitable for archival or Obsidian knowledge bases.

Features

• Thinking Process Preservation: Extracts and formats the Model's "Chain of Thought" as blockquoted text (> Thinking: ...).
• Template Standardization: Outputs consistent Markdown with Frontmatter, standardized headers (User/Deepseek), and document structure (背景 / 动机, 对话正文, 关键结论 / 摘要).
• Branch Handling: Automatically detects and exports the final regenerated response in a branching conversation trace.
• Metadata: Includes created and modified timestamps in the Frontmatter using the original conversation data.

Getting Started

Prerequisites

• Python 3.9+

Setup

Prepare three required files/paths:

• DeepSeek export file: conversations.json
• Output directory for markdown files
• Markdown template file with placeholders

Template placeholders supported:

• {title}
• {conversion_created_time}
• {conversion_export_time}
• {content}

Run Conversion

Execute the main script from the repository root with required arguments:

python3 src/main.py \
  --input ./data/conversations.json \
  --output-dir ./deepseek_exported_md \
  --template ./output_template.md

You can also run the installed CLI command after package installation:

deepseek-md-export \
  --input ./data/conversations.json \
  --output-dir ./deepseek_exported_md \
  --template ./output_template.md

Optional flag:

• -f, --force: overwrite existing markdown files and continue export.
• Without --force, when exporter detects an existing target file, it will stop the whole remaining export immediately.

Output

Converted files will be generated in the directory specified by --output-dir. Filenames follow the pattern: YYYYMMDD-Title.md.

Packaging & Publish (Poetry)

Build wheel and source distribution:

poetry build

Publish to PyPI (token should be configured first):

poetry config pypi-token.pypi <your-pypi-token>
poetry publish --build

Optional test publish to TestPyPI:

poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry config pypi-token.testpypi <your-testpypi-token>
poetry publish --build -r testpypi

Install from local dist for quick verification:

pip install dist/*.whl
deepseek-md-export --help

Fetch the template branch from the remote repository:

git fetch origin template

Merge the template branch into your local repository to get started:

git merge origin/template --allow-unrelated-histories

[!NOTE] If you'll use GitHub copilot, make sure to keep .github/instructions folder clean and simplest, or it may make context understanding and code generation worse, such as:

agent, instructions and prompts should not conflict each other.

The priority of them is:

Personal Instructions > Repository Instructions > Agent > Prompts > Your messages.

Contributing

Any contributions made are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'feat(module):add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Top contributors:

License

All code is licensed under the AGPL-3.0 license. See LICENSE for more information.