Metadata-Version: 2.4
Name: scrivenite
Version: 0.1.0
Summary: Convert Scrivener projects to Obsidian-compatible Markdown, preserving binder structure, links, and metadata
Author-email: Kapil Krishnakumar <krishnakumar.kapil@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Kapil Krishnakumar
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/krishnakumar-kapil/scrivenite
Project-URL: Issues, https://github.com/krishnakumar-kapil/scrivenite/issues
Keywords: scrivener,obsidian,markdown,pkm,conversion
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click
Requires-Dist: lxml
Requires-Dist: pypandoc
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: dev
Requires-Dist: debugpy; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="assets/logo.png" alt="Scrivenite Logo" width="200">
</p>

# Scrivenite

Convert Scrivener projects to Obsidian-compatible Markdown — preserving your binder structure, internal links, and inspector metadata.

<a href="https://www.buymeacoffee.com/krishnakumarkapil" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 40px !important;width: 145px !important;" ></a>

## Features

- 📁 **Binder Structure Preserved**: Your Scrivener folder hierarchy maps directly to folders in your Obsidian vault, with optional `01 - ` ordering prefixes so the Manuscript reads in binder order
- 🔗 **Wikilink Conversion**: Internal Scrivener links (`scrivlnk://` and `scrivener://`) become Obsidian `[[Wikilinks]]`, with aliases when the link text differs from the title
- 🏷️ **YAML Frontmatter**: Every note gets frontmatter with its original `scrivener_id` and the document title as an alias, for robust search and cross-referencing
- 📋 **Metadata Rescue**: Synopses, inspector Notes, and inline Comments are appended to each note under `## Synopsis`, `## Notes`, and `## Comments` headers
- 🖼️ **Media Support**: Images and PDFs are copied over with companion `.md` files containing `![[embeds]]`
- 🧹 **Clean Markdown Output**: Strips RTF artifacts, excessive escaping, Scrivener compile placeholders (`<$PROJECTTITLE>`, `<$wc100>`, …), and stray backticks
- 🔀 **Collision-Safe Filenames**: Titles become safe filenames (truncated to 100 chars); name collisions get a short UUID suffix

## Prerequisites

- Python 3.8 or higher
- [Pandoc](https://pandoc.org/installing.html) (macOS: `brew install pandoc`)

## Installation

```bash
git clone https://github.com/krishnakumar-kapil/scrivenite.git
cd scrivenite
pip install -e .
```

## Usage

Point the script at the `.scrivx` file **inside** your `.scriv` project bundle:

```bash
python scriv_to_obsidian.py path/to/MyNovel.scriv/MyNovel.scrivx output_folder
```

### Options

| Option | Description |
|---|---|
| `-v, --verbose` | Detailed logging of every item processed |
| `--clear` | Delete the output folder before converting (useful when re-running) |
| `-o, --ordered-folders` | Folder titles whose contents get `01 - ` ordering prefixes (default: `Manuscript`; repeatable) |
| `--skip-trash` | Don't convert the contents of the Trash folder |
| `--conservative` | Disable opinionated cleanup heuristics (stray-backtick stripping, character-sheet header promotion). Use if your documents contain inline code or literal backticks |

Example with options:

```bash
python scriv_to_obsidian.py MyNovel.scriv/MyNovel.scrivx vault/MyNovel --clear -o Manuscript -o Characters -v
```

### Example Project Structure

Input Scrivener binder:

```
MyNovel.scriv
├── Manuscript
│   ├── Chapter 1
│   │   ├── Scene 1
│   │   └── Scene 2
│   └── Chapter 2
└── Characters
    └── Protagonist
```

Generated Obsidian vault:

```
output_folder/
├── Manuscript/
│   ├── 01 - Chapter_1/
│   │   ├── 01 - Scene_1.md
│   │   └── 02 - Scene_2.md
│   └── 02 - Chapter_2/
└── Characters/
    └── Protagonist.md
```

## Troubleshooting

- **"File name too long" errors**: Filenames are automatically truncated to 100 characters — update to the latest version if you still see this.
- **Backticks around normal text**: An artifact of RTF conversion; the cleanup pass removes them. Please open an issue with a sample if any slip through.
- **XML errors on start**: Check that you passed the `.scrivx` file (not the `.scriv` folder) and that it isn't empty (0 bytes).
- **Pandoc errors**: Make sure `pandoc` is installed and on your `PATH` (`pandoc --version`).

## Roadmap

- Publish to PyPI (`pip install scrivenite`)
- Fully configurable header detection (currently tuned for character-sheet templates)
- Long-term: a native Obsidian plugin for 1-click imports

## Development

Install with test dependencies and run the suite:

```bash
pip install -e ".[test]"
pytest
```

For iterating on cleanup rules or link resolution, convert into the same output directory each time (with `--clear`) so you can diff results in one vault. A `--debug-port 5678` option is available for attaching a remote debugger (`pip install debugpy`).

### Project Structure

- `scriv_to_obsidian.py`: Main script with conversion logic
- `tests/`: Unit tests and a sample Scrivener project under `tests/data/`

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the tests
5. Submit a pull request

Bug reports with weird RTF edge cases or unusual Scrivener templates are especially welcome — they make the parser more robust for everyone.

## License

MIT License - See LICENSE file for details
