scrivener-parser

Unofficial TypeScript parser for Scrivener .scriv projects.

This is an independent implementation, not affiliated with or endorsed by Literature & Latte.
Based on the Scrivener File Format Specification — Scrivener Version 3.0, File Format Version 2.0 (23 January 2018).

Parses a .scriv project directory and exposes its contents as plain JavaScript structures:

• Binder tree (documents, folders, hierarchy)
• RTF document content (plain text, style spans, annotations, footnotes, tables, images)
• Project metadata (labels, statuses, section types, custom fields, collections)
• Compile settings and formats
• Snapshots
• Project resources (styles, search index)

Installation

npm install scrivener-parser

Usage

import { parseScrivenerProject } from 'scrivener-parser';
import { loadDirectoryAsArchive } from 'scrivener-parser/archive/node';

const archive = await loadDirectoryAsArchive('./my-project.scriv');
const project = parseScrivenerProject(archive, {
  decodeRtf: true,
  loadSnapshots: true,
});

console.log(project.info.title);
console.log(project.binder.length, 'root items');
console.log(Object.keys(project.documents).length, 'documents');

The loadDirectoryAsArchive helper is Node.js / CLI only. In a browser context, construct a ScrivenerArchive directly from File or FileSystemDirectoryHandle entries.

API

parseScrivenerProject(archive, options?)

Returns a ParsedScrivenerProject with the following fields:

Field	Description
info	Project title, identifier, and version
binder	Binder tree (ScrivenerBinderNode[])
documents	Document content keyed by UUID
metadata	Labels, statuses, section types, custom metadata, collections
settings	Compile settings, project preferences, UI state
compileFormats	Compile format definitions
resources	Styles, search index, checksums
snapshots	Snapshots keyed by document UUID
stats	Writing history and word count targets
compilePlan	Resolved compile layout per binder node

Parser options

{
  decodeRtf?: boolean;            // Parse RTF content (default: false)
  loadSnapshots?: boolean;        // Load snapshot files
  includeBinaryAssets?: boolean;  // Include raw binary data (icons, images)
  extractStyleSpans?: boolean;    // Extract style span positions
  extractInlineAnnotations?: boolean;
  extractLinkedImages?: boolean;
  extractEmbeddedImages?: boolean;
  extractHyperlinks?: boolean;
  extractBookmarks?: boolean;
  extractFields?: boolean;
  extractTables?: boolean;
  extractPlaceholders?: boolean;  // Collect compile placeholders used
  computeTextCounts?: boolean;    // Word and character counts
  normalizeBinderSections?: boolean;
  attachBinderMetaToDocs?: boolean;
}

Exports

Entry point	Contents
scrivener-parser	Parser, types, and query utilities
scrivener-parser/archive/node	Node.js directory loader

Examples

The examples/ directory contains ready-to-run scripts:

• inspect-sample.ts — Print a project summary (binder, documents, labels)
• export-writing-history.ts — Export writing statistics to CSV
• filter-custom-metadata.ts — Extract binder nodes by custom metadata field

pnpm tsx examples/inspect-sample.ts path/to/project.scriv
pnpm tsx examples/export-writing-history.ts path/to/project.scriv --out history.csv
pnpm tsx examples/filter-custom-metadata.ts path/to/project.scriv --field date

Development

pnpm test        # Run test suite
pnpm run lint    # Type-check
pnpm run build   # Build dist/

The integration test in test/tutorial-sample.test.ts requires the Scrivener Tutorial project at sample/Tutorial.scriv. Copy your Scrivener Tutorial there to enable it; all other tests use self-contained synthetic fixtures.

License

GPL-3.0-or-later — see LICENSE.