Presswork User Manual (EN)

This manual covers every Presswork feature, with a guided path through each area of the app.

1. Overview

Presswork is a professional Markdown editor for publishing and self-publishing. It combines clean writing, editorial tools (style, synopsis, versions) and professional exports (PDF, PDF/X, EPUB, DOCX, HTML, ICML, FDX). It includes Typst for fast PDFs and supports LaTeX + Ghostscript for certified PDF/X.

2. Requirements and installation

• Included: Pandoc, Typst (Base PDF), internal engines.
• Optional (Pro): LaTeX and Ghostscript for certified PDF/X.

Where to check:

• Tools → Export Check: verification and installation guidance.

3. Modes and licenses (Base / Pro)

• Base: simplified interface, fast PDF with Typst, fewer options.
• Pro: PDF/X, preflight, multi-export, advanced options and full editorial tools.
• Switch on the fly with the Base/Pro toggle in the header; the full plan and the License are managed from Settings → App → Workspace view.

4. Main interface

• Header: quick access to Document, Tools, Export, View, license, manual.
• Editor: Markdown area with toolbar and shortcuts.
• Sidebar: Outline, Snapshot, Backlink, Scrivener.
• Status bar: words, characters, line/column, goals.

5. Documents menu

• New: create a new document.
• Save MD / Save as…: save as .md.
• Import document: Word (.docx, .doc), ODT, HTML, Markdown, PDF, ICML, Final Draft. Images come in with the text: pictures from a Word document — including Excel tables pasted as an image — and images embedded in a PDF are extracted into a folder next to the imported file. Whatever is vector drawing inside a PDF (many charts are) is not an image and cannot be extracted.
• Open project: load a chapter-based project.
• Structure Mode: chapter/order management.
• Manage Project: create/update editorial projects.
• Print: print the current document.
• Versions: autosave history and restore.

Recommended flow:

1. Create a document or project.
2. Save often.
3. Use Versions to recover revisions.

6. Tools menu

• Goals: daily or per-document word targets.
• Statistics: writing trends, pace, difficulty, flow.
• User Guide: built-in manual.
• Export Check: verifies LaTeX/Ghostscript.
• Command Palette: command search (Ctrl/Cmd + P).
• Style Analysis: repetitions, readability, tone, inclusivity.
• AI Assistant: summaries, rewrites, consistency.
• Vim Mode: Vim commands.
• Collab: P2P collaborative sessions with quick invite via session ID.
  • Quick start: open Tools → Collab, set your name, create or paste a session ID (pw-...) and press Connect.
  • In a call: use the microphone and camera toggles in the floating panel; if WebRTC fails, configure the WebSocket relay (presswork-collab-relay-url).
• Tour: guided walkthrough of special formats.
• Digital Signature: sign PDFs with a certificate (Pro).

7. Export menu

Main formats

• PDF (Typst, fast)
• PDF/X (LaTeX, certified)
• Screenplay PDF (Hollywood)
• FDX (Final Draft)
• DOCX / ODT
• EPUB
• HTML
• ICML (InCopy/InDesign)

Options

• PDF style: PDF template selection.
• PDF/X: ICC profile, validation, embedded fonts.
• Crop marks/Bleed: print options.
• EPUB metadata + Cover.
• Preflight: quality and print checklist.
• Export history: export log.
• Multi Export: several files into one.
• Multi-format export: PDF + EPUB + HTML etc.
• Export with Assets: includes images/resources.
• Convert Folder: batch conversion.

8. View menu

• Modes: Writing, Code, Preview, Page, Split.
• Language: 9 UI languages.
• Theme: Light/Dark.
• Typewriter: centered active line.
• Focus Mode: hides the UI (F11).
• Presentation: fullscreen slides.
• Accessibility: text size, contrast, dyslexia-friendly font.

9. Editor toolbar

• Formatting: bold, italic, underline.
• Headings: H1/H2/H3.
• Elements: links, images, inline/block code.
• Lists: bulleted/ordered.
• Quotes.
• Tables.
• CriticMarkup: insert, delete, comment.
• Templates: layout presets.
• Metadata: YAML front matter.
• Snapshot: scene snapshots.
• Synopsis: per-chapter summaries.

10. Sidebar panels

• Outline: section navigation.
• Snapshot: snapshot management.
• Backlink: links between documents.
• Scrivener: chapters and drag&drop.
• Scene Navigator: for screenplays.

11. Writing in Markdown

Basic syntax

• # Heading / ## Subheading
• **bold**, *italic*
• - list / 1. numbered list
• [link](url)
• ![alt](image)
• > quote
• \newpage for a page break

Tips

• Drag & drop images.
• Use Split or Preview to check the layout.

12. Templates

• Built-in templates: available from the toolbar (Tpl).
• Custom templates:
  • Import a single file or a folder (Templates menu → "Import file / Import folder").
  • Automatic classification into tabs: css→UI Kit, xlsx/xls/ods/csv→Business, others→Documents.
  • Custom badge and full tooltip on hover (name + description).
  • .md: loadable in the editor.
  • .tex/.pdfx/.pdft: usable as PDF export styles.
  • .xlsx/.xls/.ods/.csv: usable in data sheet/report workflows.
• UI↔PDF auto-pair: CSS themes can auto-match the PDF template (toggle + Unpair).
• Shared library: save shared typographic presets.
• Full template feature reference: docs/template-functions-overview-en.md.

13. Metadata and front matter

• Metadata editor for title, author, ISBN.
• YAML front matter for consistent exports.
• EPUB: cover and metadata strongly recommended.

14. Projects and Structure Mode

1. Documents → Manage Project.
2. Create the project folder.
3. Add chapters (.md).
4. Reorder with drag&drop.
5. Export everything with automatic ordering.

15. Exports in detail

15.1 Base PDF (Typst)

• Fast, no LaTeX needed.
• Ideal for drafts and reviews.

15.2 PDF/X (LaTeX)

• Uses a certified template.
• Requires LaTeX + Ghostscript.
• Supports ICC, validation and preflight.

15.3 Screenplay PDF

• Hollywood layout.
• Fountain-compatible.

15.4 FDX (Final Draft)

• Export for film workflows, with a .breakdown.json report alongside (scenes, characters, tags).
• Dual dialogue: add ^ after the second character's name (GUIDO^) — in Final Draft the two speeches appear side by side (native dual dialogue); importing an .fdx brings the ^ back automatically.
• Production tags: right-click a selected word → Tag for production, or write [[prop: flashlight]] or #prop: flashlight at the end of the line. In FDX they become native Tagger tags (word highlighted, category in the breakdown); in other formats the markers are removed; tags applied in Final Draft come back on import.
• Main keys (Italian or English): prop, costume, vehicle, sound, music, makeup, animal, effects, location, note.
• Title and author (front matter, or # Title + "by …" at the top of the document) go to the Final Draft Title Page.

15.5 DOCX/ODT

• Conversion via Pandoc.

15.6 EPUB

• Metadata + cover recommended.
• Compatible with digital stores.

15.7 HTML

• Web output with resources.

15.8 ICML

• Mapped styles for InDesign/InCopy.
• Headings, lists, quotes and screenplay converted to dedicated styles.
• Included template presets + custom .icml import.
• Real footnotes (numbered by InDesign), links with destinations, tables with headers and alignments, images as linked frames (Links panel), superscript/subscript and small caps — inside cells, notes and links too.
• Faithful re-import: an exported ICML reopened in PressWork preserves the document (round-trip verified in CI, long manuscripts included).

15.9 Excel

• Excel export with scene, character and production breakdown.
• Template support: writes into existing sheets to keep base styles.
• Multi-sheet import into Markdown tables (with type/cell metadata).
• Sheet and range selection at import time to avoid unwanted data.
• Chart Mapper: optional, generates preview charts from Excel data.

16. Advanced export

• Multi Export: merges several documents.
• Multi-format export: generates PDF+EPUB+HTML into one folder.
• Export with Assets: copies images and resources.
• Export history: log and results.

17. KDP (Amazon)

• Quick Export: PDF + EPUB with KDP naming.
• Calculator: sizes and margins.
• KDP templates: dedicated covers/layouts.
• ePub validator: checklist, Kindle preview and downloadable report.

18. Style analysis

• Long sentences, repetitions, passive voice.
• Inline suggestions.
• Readability metrics.

19. AI Assistant

• Summaries, rewriting, consistency, titles.
• Cloud services ready in the menu: OpenAI, Anthropic (Claude), Mistral and aggregators such as OpenRouter. Picking one sets address and model: all that's left is pasting the key.
• Each service remembers its own key: switching between them no longer means typing it again. Keys live in the operating system keychain, not in an application file.
• Local models: «Detect Ollama» lists the ones installed on your computer. No key needed there, and nothing leaves the machine.
• Connection test checks the channel you are actually using — the cloud one if you have a key, the local one otherwise — and says which one it verified.

20. Collaboration (P2P)

• Shared sessions with colored remote cursors, inline comments and live sync.
• Built-in voice/video calls during the session.
• Shareable session ID (pw-...) to quickly invite other users.

How to use it (step-by-step)

1. Open Tools → Collab and pick a recognizable name.
2. Create a new session or paste the ID received from a colleague.
3. Wait for the Online status and check the participants in the collaboration dock.
4. If you need voice/video, start the call from the Collab panel and use the mute/camera buttons.
5. On restrictive corporate networks, set the WebSocket relay (localStorage key: presswork-collab-relay-url).

21. Digital signature

• Sign PDFs with a PAdES-T certificate.
• RFC 3161 timestamp (requires network).

22. Presentation

• Turns documents into slides.
• Configurable layouts and palettes.

23. Accessibility

• Text size 12–18px.
• High contrast.
• Dyslexia-friendly font.

24. Main shortcuts

• Ctrl/Cmd + S → Save
• Ctrl/Cmd + N → New
• Ctrl/Cmd + P → Command Palette
• Ctrl/Cmd + Shift + P → Presentation
• F11 → Focus Mode
• Ctrl/Cmd + B/I/U → Bold/Italic/Underline
• Ctrl + Alt + V → Vim

25. Troubleshooting

• PDF/X unavailable: install LaTeX + Ghostscript and restart.
• Templates not visible: use "Open templates folder" and check the extensions.
• Slow export: disable validation while drafting.

26. Useful paths

• Custom templates: presswork/templates folder inside the user configuration directory.
• PDF/X ICC: presswork/pdfx folder.

Presswork combines simplicity with professional editorial tools: write fast in Base, publish in Pro.

Recent updates (Data Hub / Charts)

• Inserting a chart from the Excel Data Hub now shows an immediate image preview in the editor too, not only in the preview panel.
• The inline preview has been reduced (about 50%) to be less intrusive while writing.
• Two-way toggle: 📝 Show code opens the chart-data block, 🖼️ Back to chart restores the image view.
• The chart-data block stays in the Markdown to guarantee compatibility with preview/render/export.
• Inserting a table or chart as an image now saves the file into the document assets (docname.assets/images/) and only the Markdown reference enters the editor: it works even with very large sheets.
• If the document is not saved yet, the app offers to save it on the spot (as with image drag&drop); declining inserts the table as Markdown text and keeps the chart in the sheet.
• The text/image prompt also understands answers like "png", "jpg", "image", "photo"; an unrecognized answer repeats the question.
• The data grid follows the active light/dark theme.
• Save as Template: dialog redesigned in the app's style and translated. Requires data in the grid and a model in the editor with {{ColumnName}} placeholders; "Generate Markdown" repeats the model for each row.
• Excel export (breakdown): reads the editor text (INT./EXT. scenes or # chapters); if no scenes are found it now warns instead of generating an empty file.
• Simplified Tables menu: removed the duplicate entry "Import as template" (identical to "Open Tables sheet").
• Import/Export panel: new Batch tab (next to Base format / Pro print / Screenplay / Publishing) with the batch actions: Convert Folder, Multi Export, Multi-format, With Assets. Advanced options only show what applies to the chosen format.
• 🧪 Verify ICML: in the export panel (ICML format) it checks the generated document — hierarchy, front matter, escaping, empty paragraphs — without writing anything to disk; details appear in an in-app window. The same check also runs on every ICML export.
• Safer FDX export: generic Markdown (lists, tables, notes) always becomes Action — never Character/Dialogue by accident; real screenplays are still interpreted (scenes, characters, dialogue, transitions). \newpage becomes a real page break (in ICML too, via a remappable "Page Break" style).
• Print via PDF: the Print button generates a temporary PDF (Typst, same typography as the exports) and opens it in the system viewer — print from the native dialog with a faithful preview.
• Settings reorganized: Installations section (one-click LaTeX, Ghostscript status), compact language view, Dark/Light theme chips. The AI panel's quick prompts are collapsible.

27. In-depth feature analysis (gaps filled)

This section covers advanced features that often go unused because they are not very visible in the menus.

27.1 AI: configuration, diagnostics and response quality

• Configurable cloud/local endpoints (OpenAI-compatible, Ollama, LM Studio) via PRESSWORK_AI_ENDPOINT, PRESSWORK_AI_MODEL, PRESSWORK_AI_API_KEY variables.
• AI connection diagnostics with an exportable JSON report (useful for tech support/IT teams).
• Response style control (concise/balanced/detailed), technical prompt preview and last-prompt retry.
• Endpoint/model pin per project: keeps editorial consistency across documents.

27.2 Statistics: calculation method (operational)

• Average productivity: computed on the daily history (7 days / 30 days).
• Writing speed: total words divided by the session window (words/hour and words/min).
• TTR (Type-Token Ratio): unique words / total words.
• MSTTR: average TTR over 50-word windows (reduces bias on long texts).
• Realtime flow state: average keystroke interval + recent deletion ratio.
• Completion forecast: optimistic/pessimistic estimate using 7d vs 30d averages.

27.3 Advanced exports missing from the quick guide

• Final Draft (.fdx): maps headings to real Scene Headings, supports notes/page breaks/scene numbering and generates a .breakdown.json sidecar.
• ICML: advanced typographic mapping (headings/lists/quotes/screenplay) + presets + custom .icml import.
• EPUB/ICML wizard: blocks the export until minimal metadata (title/author/ISBN) and cover are set.
• PDF signing: PKCS#7 detached + RFC 3161 timestamp.

27.4 Bundle mode (.pwk)

• Main action: Export with destination choice.
• Automatic output targets to reduce manual path errors.
• Header toggle to temporarily show the classic quick exports.

27.5 Collaboration (P2P) in real-world contexts

• Shareable pw-... session ID, colored remote cursors, inline comments, live sync.
• Voice/video call built into the same editorial session.
• WebSocket relay fallback when WebRTC is blocked (corporate networks/firewalls), via the presswork-collab-relay-url key.

27.6 Template system (professional use)

• File/folder import with automatic classification (Business / Documents / UI Kit).
• Support for binary and spreadsheet templates for report workflows.
• UI↔PDF auto-pair to link editor theme and export style, with an Unpair option.

27.7 Recommended operational checklist

1. Set Base/Pro mode based on the deliverable.
2. Verify prerequisites in Export Check (LaTeX/Ghostscript only if PDF/X is needed).
3. Run Preflight before delivery.
4. For EPUB/ICML complete the metadata + cover wizard.
5. For signed documents enable PKCS#7 signing + timestamp.
6. In teams, store the Collab Session ID and relay fallback in your internal policy.

28. Connect an assistant (MCP)

Since 4.2, PressWork acts as an MCP bridge: chat AI assistants (Claude Desktop, Codex CLI, Gemini CLI…) read your .pwk projects right on your computer — chapters, notes, statistics — with no copy-paste. Read-only: the bridge has no write tool at all, only seven readers. If the assistant you connect has its own tools for reaching files on your computer, those don't go through PressWork.

• One-click setup: Settings → AI → Connect an assistant (MCP) → "Set it up for me" (Claude Desktop / Codex CLI / Gemini CLI). The open project's folder gets connected, with every .pwk inside it.
• Fully quit the assistant before configuring (Claude Desktop rewrites its own config on exit), then reopen it. The app backs up the config before writing anyway.
• Folders add up: configure from projects in different folders and the assistant sees them all. Works even with PressWork closed.
• On Claude: regular chats live in the cloud and can't reach your machine — pick the "On your computer" activity or tick the presswork connector.
• Other MCP clients (Cursor, OpenCode…): manual config snippet to copy. With Export the Skill you generate the skill that teaches Claude to make the most of your projects (add it once, it sticks forever).
• Privacy, stated honestly: whatever the assistant reads is sent to its cloud service to produce the answer — like a copy-paste, only automatic. Don't connect projects you wouldn't send in a chat.
• Requires the Complete working view.

29. Branches and chapter variants

Two different tools answering the same question — "what if instead…" — at two different scales.

A branch is another book. In every book, each chapter can have its own variants.

29.1 Branches

• A branch is an alternative version of the whole document: change the ending, drop a character, try another structure. The main document stays intact.
• Panel: Ctrl/Cmd+Shift+B or from the menu. Open a branch and you go inside it: from that moment you write there.
• You always see where you are: a pill with the branch name appears at the bottom of the window. No pill = you are on the main document, the one that goes to print.
• Promote makes the branch the real document (the old main one is archived as a branch). Diff compares line by line. Export detaches the branch into an independent .pwk.
• All branches live inside the same .pwk: no extra files, no Git.
• The Synopsis cards show where the roads fork: each chapter card carries a mark in the branch colour where that chapter differs, struck through where it does not exist. One click opens Branches. Cards identical in every branch stay clean: silence means «nothing has diverged here». Inside a branch the comparison includes the main document, which is exactly what you need to compare against while exploring another road.
• Chapters that live only elsewhere are not dropped: at the bottom of the Synopsis, when needed, you get the list of chapters that exist only in another version. It matters most for renamed ones, since chapters are identified by their title.

29.2 Chapter variants

• A variant is a second draft of a single chapter: on paper it was crossing out a passage and rewriting it beside. Only one stays alive in the text, and that is the one that goes into the files.
• Create: Synopsis → hover the chapter card → ⑂ in the top right. The current text becomes the first draft; you name the new one.
• Switch: click the ⑂ pill on the card and pick. The active one is marked "in the text". Only that chapter changes.
• Delete: the bin in the menu. The active variant cannot be deleted: switch to another one first.
• Where you see it: the status bar, next to the word count — ⑂ variant: name. If the chapter your cursor is in has none, it says so anyway, dimmed.
• Every branch has its own variants: the ones created inside a branch do not show on the main document, and that is by design.

29.3 If something doesn't add up

• Renamed a chapter, variants gone: they are not lost. At the bottom of the Synopsis there is a "Variants without a chapter" band holding everything that currently has no home; the "assign to…" menu puts them back. PressWork tries to follow renamed titles on its own, but when it isn't sure it prefers showing you the material over guessing.
• Undo applies here too: switching variant is a text edit like any other (Ctrl/Cmd+Z).
• On disk: versions/branches/<id>/ and versions/variants/ inside the .pwk. Plain .md files: even without PressWork the work is readable.