scrivenite 0.2.0

Convert Scrivener projects to Obsidian-compatible Markdown, preserving binder structure, links, and metadata

Scrivenite

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

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

Download the Mac App (no setup required)

Not a terminal person? Grab Scrivenite.dmg from the latest release — a standalone Mac app (Apple Silicon) with everything bundled, including pandoc. Open the DMG, drag Scrivenite to Applications, and follow the first-launch note inside the DMG (the app is unsigned, so macOS asks you to approve it once via System Settings → Privacy & Security → "Open Anyway").

Then: pick your .scriv project, pick an output folder, click Convert.

Installation (command line)

Requires Python 3.8+ and Pandoc (macOS: brew install pandoc).

pip install scrivenite

Or from source:

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

Usage

Point the tool at the .scrivx file inside your .scriv project bundle:

scrivenite path/to/MyNovel.scriv/MyNovel.scrivx output_folder

(python scriv_to_obsidian.py … works too from a source checkout, and scrivenite-gui launches the same graphical interface as the Mac app.)

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:

scrivenite 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

• Signed & notarized macOS app (no "Open Anyway" step), plus an Intel build
• 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:

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).

To build the standalone Mac app + DMG locally (bundles Python, Tcl/Tk, and pandoc via pypandoc-binary):

./build_macos_app.sh          # outputs to /tmp/scrivenite_build/dist/

The release workflow builds and attaches the DMG automatically when a v* tag is pushed.

Project Structure

• scriv_to_obsidian.py: Main script with conversion logic
• scrivenite_gui.py: Tkinter GUI (what the Mac app runs)
• build_macos_app.sh: PyInstaller + DMG build script
• 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