Skip to content

Repository files navigation

Joplin Scriptwriter Plugin

This is a plugin for Joplin. Refer to joplin toc.


A screenwriting plugin for Joplin built around the plain-text Fountain markup standard. Write scripts with industry-standard visual formatting, a two-key (Tab / Enter) workflow inspired by KIT Scenarist and Story Architect (STARC), context-aware autocomplete, live runtime estimation, outline navigation, and US-standard PDF export.

Interface Preview

Features

  • 100% Pure Fountain Storage: Your notes stay clean, valid Fountain plain text without proprietary XML or hidden markup. Visual indentation and typography are applied dynamically inside the CodeMirror 6 Markdown editor.
  • Per-Note Screenplay Mode: Toggle screenplay mode for any note with a single click on the filmstrip icon on the toolbar or via the side panel button (managed cleanly via the fountain tag).
  • Two-Key Workflow (Tab, Enter, & Shift+Enter):
    • Empty lines:
      • Pressing Tab on an empty Action line starts a Character (@) and opens the character list. Pressing Tab again cycles: Character (@) → Transition (> ) → Action.
      • Pressing Enter on an empty Action line opens the Scene Prefix selector (INT., EXT., etc.).
      • Pressing Tab on an empty Dialogue line inserts a Parenthetical (); pressing Enter exits back to Action.
    • Filled blocks (at line end):
      • Scene Heading: Tab or Enter → new Action block.
      • Action: Tab → new Character (@) with autocomplete; Enter → new Action block.
      • Character: Tab → Parenthetical (); Enter → Dialogue line. Typing additional letters at the end of an existing character name automatically capitalizes them to preserve valid Fountain formatting.
      • Parenthetical: Tab or Enter from anywhere inside single-line or multi-line parentheses exits cleanly onto a new Dialogue line below ).
      • Dialogue: Tab → Parenthetical (); Enter → new Action block.
      • Transition: Tab or Enter → new Scene Heading (INT. ).
    • Soft line breaks (Shift+Enter): Inserts a line break within the current block (including multi-line parentheticals and Fountain two-space dialogue breaks) without changing block formatting.
    • Safe Separator Editing: Typing or pressing Tab/Enter inside a single empty separator line between two existing blocks automatically preserves blank lines above and below so adjacent dialogues and characters never merge.
  • Multilingual Scene & Character Markers (7 Languages):
    • Built-in dictionaries for English (en), French (fr), Spanish (es), Italian (it), German (de), Russian (ru), and Ukrainian (uk).
    • Includes localized Scene Prefixes, Time of Day markers, Transitions, and Character Extensions ((V.O.), (O.S.), (O.C.), (SUBTITLE), (CONT'D), etc.).
    • Use a single language (e.g., en) or combine multiple languages at once (e.g., en, fr or es, it) so older and newer scripts work side by side.
  • Step-by-Step Smart Autocomplete:
    1. Scene Prefixes: Triggered by Enter on an empty Action line or by typing at the start of a block (INT., EXT., INNEN, EST., etc.). Selecting a prefix automatically opens location suggestions.
    2. Locations: Collected from the active script, other #fountain notes in the notebook, and project bibles.
    3. Time of Day: Triggered automatically after typing - in any scene heading (DAY, NIGHT, JOUR, DÍA, GIORNO, TAG, etc.).
    4. Dialogue-Alternating Character Suggestions: Triggered when typing @ (via Tab) or uppercase letters. Characters are sorted by recency and dialogue alternation (the previous speaker appears first, followed by the last speaker, then earlier speakers in reverse chronological order). Confirming a character jumps directly to the Dialogue line.
    5. Character Extensions: Typing ( after any character name (e.g., ALEX ( ) opens localized extensions ((V.O.), (O.S.), etc.) as well as any custom parenthetical extensions already used in your script.
  • Hybrid Project Dictionary (#fountain-bible): Automatically gathers characters and locations from the active script, all other #fountain notes in the same notebook, and reference notes tagged with fountain-bible.
  • Screenplay Side Panel:
    • Sticky header with calibrated page count (~1 page = 1 minute matched to US Letter PDF output) and runtime estimation.
    • Scrollable interactive Outline (Sections #, Scene Headings, and toggleable Synopses =) with click-to-scroll navigation.
    • Characters list (with dialogue line counts) and Locations index.
  • US-Standard PDF & .fountain Export:
    • Export via Note → Export → Fountain Screenplay (PDF) or Fountain Screenplay (.fountain).
    • Configurable title page (Title, Credit, Author, Source, Draft date, Contact), optional left-margin scene numbering, synopsis inclusion, and automatic saving of title metadata back to the note header.
    • Uses US Letter format (1.5" left margin, 1" top/right/bottom margins, 12pt monospace font) with full Cyrillic and Latin support.

Installation

Method 1: Directly via the Joplin App (Recommended)

  1. Launch Joplin on your desktop.
  2. Navigate to your global configuration window: Tools > Options (or Joplin > Preferences on macOS).
  3. Select the Plugins segment tab from the sidebar interface.
  4. Type scriptwriter directly inside the search inputs field bar.
  5. Click Install, then gently restart the Joplin application bootstrap to activate the panel layout.

Method 2: From Release (.jpl)

  1. Download the latest .jpl file from the Releases page.
  2. Open Joplin → Tools → Options (or Joplin → Settings on macOS) → Plugins.
  3. Click the gear icon ⚙️ next to the search bar and select Install from file.
  4. Choose the downloaded .jpl file and restart Joplin.

Method 3: Building from Source

git clone https://github.com
cd joplin-plugin-scriptwriter
npm install
npm run dist

The compiled .jpl archive will be generated inside the publish/ directory.


Usage Guide

  1. Switch to the Markdown Editor: Make sure Joplin is in Markdown editor mode (M↓ icon in the top-right corner of the editor), as CodeMirror plugins are active in Markdown mode.
  2. Activate Screenplay Mode: Click the filmstrip icon on the toolbar (or click Enable Fountain Mode in the right side panel). The note will be tagged with fountain, and the screenplay layout will activate immediately.
  3. Create a Series / Project Bible (Optional): Create a note in the same notebook, assign the tag fountain-bible, and list recurring characters and locations under ## Characters and ## Locations:
    ## Characters
    - ALEX
    - MARIA
    
    ## Locations
    - ALEX'S APARTMENT
    - COFFEE SHOP
  4. Export Your Script: Right-click the note in the note list (or open Note → Export) and select:
    • Fountain Screenplay (PDF) — configure title page fields and export a formatted PDF.
    • Fountain Screenplay (.fountain) — export a clean .fountain file compatible with Final Draft, Story Architect (STARC), KIT Scenarist, Highland, and Fade In.

Plugin Settings

Go to Options / Settings → Fountain Screenplay to configure:

  • Default Author: Pre-fills the Author field in the PDF export dialog.
  • Default Contact Info: Pre-fills the Contact field in the PDF export dialog.
  • Scene marker languages: Comma-separated list of active marker locales (en, fr, es, it, de, ru, uk). Example: en or en, ru.
  • Default PDF paper size: US Letter or A4.

License

This repository is distributed under the terms of the MIT License. You are free to copy, modify, distribute, or use this extension setup commercially, provided the original author credits remain intact. See the LICENSE file for details.

Support the Project

If this plugin saves you time and helps you keep track of your calculations, consider supporting its further development! Any contribution is highly appreciated.

💵 USDT (TRC-20): TS1x5AR87CipqAqF3bb7sqePBKqRLFEc4Q

🪙 Bitcoin (BTC): bc1qpamcvn5le907jkt5zhhd4c2r783489nts72m8m

💎 Ethereum (ETH): 0x354dc4b9cEC4fC05021Cd26734B8cc839390e5af