Metadata-Version: 2.3
Name: deepseek-json-to-markdown-converter
Version: 0.1.0
Summary: Convert DeepSeek conversations.json exports to markdown files
License: AGPL-3.0
Author: bGZo
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Description-Content-Type: text/markdown

[![Contributors](https://img.shields.io/github/contributors/bGZo/playground.svg?style=for-the-badge)](https://github.com/bGZo/playground/graphs/contributors)
[![Forks](https://img.shields.io/github/forks/bGZo/playground.svg?style=for-the-badge)](https://github.com/bGZo/playground/network/members)
[![Stargazers](https://img.shields.io/github/stars/bGZo/playground.svg?style=for-the-badge)](https://github.com/bGZo/playground/stargazers)
[![Issues](https://img.shields.io/github/issues/bGZo/playground.svg?style=for-the-badge)](https://github.com/bGZo/playground/issues)
[![Licence](https://img.shields.io/github/license/bGZo/playground.svg?style=for-the-badge)](https://github.com/bGZo/playground/blob/template/LICENCE)
[![Telegram](https://img.shields.io/badge/-telegram-black.svg?style=for-the-badge&logo=telegram&colorB=555)](https://t.me/imbGZo)

# 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:

```bash
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:

```bash
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:

```bash
poetry build
```

Publish to PyPI (token should be configured first):

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

Optional test publish to TestPyPI:

```bash
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:

```bash
pip install dist/*.whl
deepseek-md-export --help
```
Fetch the `template` branch from the remote repository:

```shell
git fetch origin template
```

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

```shell
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:

<a href="https://github.com/bGZo/playground/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=bGZo/playground" alt="contrib.rocks image" />
</a>

## License

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

