You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Manuscript Compiler <imgsrc="logo.svg"alt="Manuscript Compiler semantic tree logo"width="48"align="right">
1
+
# Manuscript Compiler
2
2
3
-
Manuscript Compiler 0.9.3 turns fiction in an Obsidian vault into DOCX, ODT, EPUB, standalone HTML, Markdown, or structured XML. It works offline, never changes source notes, and requires neither Pandoc nor another community plugin.
Only content included in the reviewed manuscript structure is exported. Project metadata, author notes, dashboards, and excluded notes are not manuscript content.
7
+
Compile structured Obsidian manuscripts into publication-ready DOCX, ODT, EPUB, HTML, Markdown, and XML files for Vellum and other publishing workflows.
6
8
7
-
The workflow has three stages: **Manuscript → Contents → Create file**. Every format is generated locally in memory, validated, and handed to the host download/share flow. Completed exports are downloaded outside the vault; the plugin does not choose or remember the final destination.
9
+
Manuscript Compiler understands a book as **Parts, Chapters, Scenes, Front Matter, and Back Matter**—not merely as a collection of Markdown files. It detects that publishing structure, lets you review and correct inclusion, roles, and order, then compiles only the manuscript you approved.
18
23
19
-
Until the plugin is listed in Obsidian's Community Plugins directory, download `main.js`, `manifest.json`, and `styles.css` from a GitHub release whose tag exactly matches the manifest version. Put the three files in a vault plugin folder named `manuscript-compiler`, reload Obsidian, and enable **Manuscript Compiler** under Community Plugins.
24
+
Designed specifically for long-form authors, it keeps research, dashboards, development notes, and excluded drafts out of the finished book while preserving the hierarchy expected by editing and publishing tools. Your source notes are never rewritten.
20
25
21
-
## Quick start
26
+
## Features
22
27
23
-
1. In File Explorer, right-click the book folder and choose **Compile manuscript from this folder**.
24
-
2. Review the detected structure and correct inclusion, roles, or order if needed.
25
-
3. Choose DOCX, ODT, EPUB, HTML, Markdown, or XML.
26
-
4. Choose the formatting controls that apply to that format.
27
-
5. Press **Create and download …**.
28
-
6. Complete the save or share flow provided by Obsidian and the operating system.
28
+
### Author Workflow
29
29
30
-
The selected folder is the exact manuscript root; it never becomes a Part or Chapter. The three-stage workspace is **Manuscript → Contents → Create file**. Contents opens as a compact outline. **Correct structure** exposes keyboard-operable inclusion, type, and ordering controls. Excluded folders collapse without losing child choices or manual order.
30
+
- Right-click any manuscript folder
31
+
- Automatic structure detection
32
+
- Manual correction before export
33
+
- Semantic review of the complete book
34
+
- One-click compilation and download
31
35
32
-
If an included note or a semantic compile choice changes after preparation, export is blocked until the preview is refreshed. Changing only the selected format or filename does not rescan, reparse, or rebuild the prepared Book.
36
+
### Publishing
33
37
34
-
## Formats
38
+
- Native DOCX
39
+
- Native ODT
40
+
- Native EPUB 3
41
+
- Native offline HTML
42
+
- Native Markdown
43
+
- Native semantic XML
44
+
- DOCX designed for Vellum workflows
35
45
36
-
-**DOCX** is native WordprocessingML for Word, Vellum, editing, and submission. Vellum and Standard Manuscript presets are fully supported.
37
-
-**ODT** is a native OpenDocument Text ZIP package for LibreOffice and compatible editors.
38
-
-**EPUB** is a native EPUB 3 reflowable package with container, package document, navigation, XHTML sections, and embedded CSS.
39
-
-**HTML** is one offline HTML5 file with embedded CSS, semantic sections, and no JavaScript or remote assets.
40
-
-**Markdown** is a deterministic, portable plain-text manuscript preserving semantic structure, emphasis, readable links, Unicode, and paragraph spacing.
41
-
-**XML** is a deterministic interchange format in the `https://manuscript-compiler.dev/schema` namespace with `schemaVersion="1.0"`. It contains manuscript content and structure, but no vault paths, profile IDs, settings, or private YAML metadata.
46
+
### Privacy
42
47
43
-
DOCX and ODT support document-style pagination controls. EPUB and HTML expose only meaningful reflowable controls. Markdown and XML expose structural content controls without print typography. No visible control is intended to be inert.
48
+
- Fully offline compilation and export
49
+
- No telemetry or analytics
50
+
- No cloud service or account
51
+
- No manuscript network access
52
+
- No external executables
53
+
- No companion plugins
54
+
- No changes to manuscript notes
44
55
45
-
The Create file screen offers **Indent first line of paragraphs** for DOCX, ODT, EPUB, and HTML. When enabled, the configured first-line indent applies only to later body paragraphs; the first paragraph after a structural heading or scene break remains unindented. When disabled, all body paragraphs—including copyright and other matter text—use zero first-line indent without changing paragraph or line spacing. The indent-size control is shown only while indentation is enabled. Markdown stays portable and does not simulate indentation with spaces, tabs, HTML, or CSS. XML stays presentation-neutral, so its consuming application controls paragraph indentation.
56
+
### Reliability
46
57
47
-
## Discovery and Cleaning
58
+
- One shared semantic `Book` model for every format
59
+
- Format-specific structural validation before download
60
+
- Deterministic structural output
61
+
- Stale-preview protection
62
+
- Comprehensive automated tests
48
63
49
-
Folders named Manuscript, Draft, Drafts, Book, Content, or Chapters can be transparent containers. Project folders such as Archive, Development, Exports, Research, Notes, Planning, Characters, Locations, Dashboards, Templates, Attachments, and old drafts are ignored by default but remain reviewable.
64
+
## Quick Start
50
65
51
-
Front and back matter are inferred from names and ancestry. Parts, Chapters, Scenes, matter, transparent containers, and ignored items can all be corrected before preparation.
66
+
1.[Install the plugin](#installation).
67
+
2. Right-click the complete manuscript folder in Obsidian.
68
+
3. Review and correct the detected structure.
69
+
4. Choose an export format and formatting preset.
70
+
5. Select **Create and download**.
52
71
53
-
For template notes, the default manuscript-body headings are Scene, Manuscript, Text, Draft, and Body. Synopsis, Revision Notes, Editing Notes, Author Notes, Development Notes, and Comments sections are removed. YAML and recognised structured project metadata are removed without treating ordinary prose beginning with words such as “Book” or “Chapter” as metadata.
72
+
See the [User Guide](USER_GUIDE.md) for the complete author workflow.
54
73
55
-
Bold, italics, combined emphasis, readable Markdown link text, punctuation, smart quotes, accented characters, and Unicode pass through the shared semantic export projection. Embedded media, complex tables, and advanced Markdown layout are outside the restrained fiction model.
74
+
## Export Formats
56
75
57
-
## Delivery, Privacy, and Platform Behaviour
76
+
| Format | Purpose |
77
+
| --- | --- |
78
+
|**DOCX**| Word editing, submission, and Vellum import workflows |
79
+
|**ODT**| LibreOffice and other OpenDocument workflows |
80
+
|**EPUB**| Reflowable EPUB 3 proofing and ebook workflows |
81
+
|**HTML**| A self-contained offline browser proof with embedded CSS |
|**XML**| Presentation-neutral semantic interchange and automation |
58
84
59
-
All formats are generated and structurally validated in memory before delivery. One platform-neutral service creates a Blob, dispatches a temporary `<a download>` exactly once, removes it, and revokes the object URL. The plugin does not know or persist the final external path. Obsidian or the host may ask where to save the file or place it in Downloads. On mobile, the same mechanism is attempted; there is no vault-output fallback.
85
+
## Capability Comparison
60
86
61
-
Completed manuscript exports are never written into the vault. Historical vault-output settings remain storage-only migration data and cannot activate an old output route. The diagnostics command may still create an explicitly requested privacy-safe Markdown diagnostics note in the vault; that is not a manuscript export.
87
+
| Capability | Manuscript Compiler |
88
+
| --- | :---: |
89
+
| Native DOCX | ✅ |
90
+
| Native ODT | ✅ |
91
+
| Native EPUB | ✅ |
92
+
| Offline operation | ✅ |
93
+
| No Pandoc | ✅ |
94
+
| No companion plugin | ✅ |
95
+
| No telemetry | ✅ |
96
+
| Open source | ✅ |
62
97
63
-
The plugin has no Electron bridge, Node filesystem export path, background network requests, telemetry, cloud service, remote assets, shell command, or external executable. Support and funding links open an external website only when the user explicitly selects them. `fflate` is the sole bundled runtime dependency and supplies ZIP creation/inspection.
98
+
## Screenshots
64
99
65
-
### Disclosures
100
+
### Plugin Settings
66
101
67
-
| Topic | Disclosure |
68
-
| --- | --- |
69
-
| External file access | Browser/host-controlled download only; the host chooses the destination. |
70
-
| Network | No background requests. Export, validation, and delivery initiation are offline. User-selected support links open in the system browser. |
71
-
| Accounts | None. |
72
-
| Payments and advertising | No advertising or in-plugin payments. An optional external donation link is identified as **Buy me a coffee**. |
73
-
| Telemetry and analytics | None. |
74
-
| Closed-source components | None. |
75
-
| Runtime dependencies |`fflate` 0.8.3, bundled under its MIT licence. |
76
-
| Vault writes | No manuscript export is written to the vault. The explicit diagnostics action can create a redacted Markdown support note. |
77
-
| Mobile | The same browser download mechanism is attempted. Some mobile hosts may block or redirect downloads; no vault fallback is used. |
102
+
103
+
104
+
*Set author defaults once, then open the compiler directly from Obsidian settings.*
105
+
106
+
### Right-click Menu
107
+
108
+
109
+
110
+
*Start from the exact folder that contains the complete book.*
111
+
112
+
### Manuscript Screen
113
+
114
+
115
+
116
+
*Confirm the manuscript root and automatically detected book structure.*
117
+
118
+
### Contents Review
119
+
120
+
121
+
122
+
*Review Parts, Chapters, Scenes, matter, warnings, and ignored notes before export.*
123
+
124
+
### Correct Structure
125
+
126
+
127
+
128
+
*Correct inclusion, publishing roles, and order without moving or rewriting source notes.*
129
+
130
+
### Create File
131
+
132
+
133
+
134
+
*Choose the output format and meaningful publishing controls, then create the file.*
135
+
136
+
### DOCX in Microsoft Word
78
137
79
-
History records bounded structural facts: time, title, format, filename, counts, generation/validation status, and whether download dispatch started. It does not record prose, Blob URLs, absolute paths, profile IDs, or warning details containing manuscript data.
138
+
80
139
81
-
##DOCX Presets
140
+
*Native DOCX opens with distinct structural formatting and named manuscript styles.*
82
141
83
-
Vellum defaults to Garamond 12 pt, 1.15 spacing, enabled 0.75 cm first-line indentation, A4, `#` scene breaks, separate Part/Chapter number and title styles, and Chapter page starts. Standard Manuscript defaults to Times New Roman 12 pt, double spacing, enabled 1.27 cm indentation, A4, `* * *` scene breaks, and Chapter page starts. Custom retains both the indentation toggle and its configured size along with the other applicable exposed values.
142
+
### DOCX in Vellum
84
143
85
-
DOCX includes native Title, Author, Front Matter Heading, Back Matter Heading, Part Number, Part Title, Chapter Number, Chapter Title, First Paragraph, Body Text, and Scene Break styles. No Part 0 or Chapter 0 is invented.
144
+
145
+
146
+
*Vellum recognises the compiled Part and Chapter hierarchy.*
147
+
148
+
### ODT in LibreOffice
149
+
150
+
151
+
152
+
*Native ODT carries the manuscript structure into LibreOffice Writer.*
153
+
154
+
### EPUB Reader
155
+
156
+
157
+
158
+
*The EPUB provides navigable contents and a reflowable reading view.*
159
+
160
+
## Documentation
161
+
162
+
-[User Guide](USER_GUIDE.md)
163
+
-[Developer Guide](DEVELOPER_GUIDE.md)
164
+
-[Architecture](ARCHITECTURE.md)
165
+
-[Security Policy](SECURITY.md)
166
+
-[Contributing](CONTRIBUTING.md)
167
+
-[Manual Release Checklist](MANUAL_TESTING.md)
168
+
169
+
## Installation
170
+
171
+
### Community Plugins
172
+
173
+
Manuscript Compiler is not yet listed in Obsidian's Community Plugins catalogue. Once available, search for **Manuscript Compiler**, select **Install**, then **Enable**.
174
+
175
+
### Manual Installation
176
+
177
+
Download `main.js`, `manifest.json`, and `styles.css` from the same [GitHub release](https://github.com/anthonyfitzpatrick/manuscript-compiler/releases). Place them directly in `<vault>/.obsidian/plugins/manuscript-compiler/`, reload Obsidian, and enable **Manuscript Compiler** under Community Plugins.
178
+
179
+
## Known Limitations
180
+
181
+
- Complex tables, embedded media, and advanced Markdown layouts are outside the semantic fiction model.
182
+
- Save and share behaviour depends on the desktop or mobile host.
183
+
- EPUB and target-application validation still require representative reader testing.
184
+
- Unusual authoring templates may require manual structure correction.
185
+
- Manuscript Compiler is not a fixed-page desktop-publishing engine.
186
+
187
+
See [Known limitations in the User Guide](USER_GUIDE.md#known-limitations) for details and recommended testing.
86
188
87
189
## Development and Validation
88
190
@@ -108,14 +210,8 @@ git diff --check
108
210
109
211
The release archive is `release/manuscript-compiler-0.9.3.zip` and contains exactly `main.js`, `manifest.json`, and `styles.css`.
110
212
111
-
Automated structural validation is not a substitute for opening outputs in Word, Vellum, LibreOffice, multiple EPUB readers, text editors, and browsers. See [MANUAL_TESTING.md](MANUAL_TESTING.md).
112
-
113
-
## Known Limits
213
+
Automated structural validation is not a substitute for opening outputs in Word, Vellum, LibreOffice, multiple EPUB readers, text editors, and browsers. See the [Manual Release Checklist](MANUAL_TESTING.md).
114
214
115
-
- Browser/host download behaviour and prompts differ by platform, and the plugin cannot verify the final filesystem copy after dispatch.
116
-
- On mobile, the host may block the download or route it through a platform share sheet. The plugin reports dispatch failure and does not write a fallback copy into the vault.
117
-
- EPUB validation is structural and does not replace EPUBCheck or live reader testing.
118
-
- Vellum import semantics require live Vellum testing.
119
-
- Unusual authoring templates may require manual structure correction or body-heading aliases.
215
+
## Licence
120
216
121
-
For a full author-oriented explanation of these limits and recovery steps, see [USER_GUIDE.md](USER_GUIDE.md).
0 commit comments