fountain2pdf
v1.0.0
Published
Professional Fountain to PDF screenplay converter for Browser and Node.js with authentic industry formatting
Maintainers
Readme
fountain2pdf 🎬📄
Professional Fountain screenplay converter for Browser and Node.js with authentic industry standard formatting. Generates pure PDF documents without relying on the browser print dialog.
✨ Features
- 🎭 Universal (Browser & Node.js): Runs in modern browsers, Node.js, Web Workers, Bun, and Deno with zero DOM dependencies.
- 🚫 No Browser Print Dialog: Generates pure binary PDF documents directly on the client side using vector drawing.
- 📐 Authentic Industry Formatting:
- Courier 12pt (10-pitch monospaced, 7.2pt character width, 6 lines/inch standard leading).
- Standard US Letter (8.5" x 11") and A4 support.
- Proper 1.5" left margin (for 3-hole punch brass brads binding), 1.0" top, bottom, and right margins.
- Accurate indentation for Action, Character cues, Dialogue, Parentheticals, and Transitions.
- Dual dialogue (side-by-side speech blocks with
^). - Professional title page generation (Title, Author, Source, Contact, Draft date).
- Scene numbering (left & right margin alignment).
- Page numbering in top-right header (suppressed on page 1).
- Orphan protection (no stranded character cues or scene headings at page bottoms).
- Smart dialogue breaks across pages with
(MORE)andCHARACTER (CONT'D). - Inline typography (
**bold**,*italic*,***bold italic***,_underline_).
- ⚡ Lightweight & Fast: Built with
pdf-liband standard PDF Courier fonts — no multi-megabyte font downloads required. - 📦 Dual ESM & CommonJS: Full TypeScript types (
.d.ts), sourcemaps, and bundled treeshakeable outputs. - 🛠️ CLI Included: Convert scripts directly from the terminal with
npx fountain2pdf.
🚀 Installation
npm install fountain2pdf💻 Usage
1. In the Browser (Client-Side)
Generate a PDF Blob, preview in an <iframe>, or trigger a direct file download without opening the browser's print dialog:
import { fountainToPdfBlob, downloadPdf } from 'fountain2pdf';
const fountainScript = `
Title: THE MIDNIGHT CIPHER
Author: Jane Doe
INT. SERVER ROOM - NIGHT
The blue glow illuminates KATE (20s).
KATE
(whispering)
Almost decrypted...
`;
// Option A: Trigger a direct PDF download (No browser print window!)
await downloadPdf(fountainScript, 'my-screenplay.pdf');
// Option B: Get a PDF Blob for preview in an <iframe> or PDF viewer
const blob = await fountainToPdfBlob(fountainScript);
const pdfUrl = URL.createObjectURL(blob);
document.getElementById('myIframe').src = pdfUrl;2. In Node.js / Server
import fs from 'node:fs';
import { fountainToPdf } from 'fountain2pdf';
const script = fs.readFileSync('script.fountain', 'utf-8');
// Returns a Uint8Array containing pure PDF bytes
const pdfBytes = await fountainToPdf(script, {
paperSize: 'letter', // or 'a4'
includeTitlePage: true,
showSceneNumbers: true
});
fs.writeFileSync('output.pdf', pdfBytes);3. Command Line (CLI)
# Convert a script to PDF
npx fountain2pdf my-script.fountain
# Specify output filename and A4 paper
npx fountain2pdf my-script.fountain output.pdf --a4
# View CLI options
npx fountain2pdf --help⚙️ Options Reference
You can pass an optional PdfExportOptions object to fountainToPdf:
const pdfBytes = await fountainToPdf(script, {
paperSize: 'letter', // 'letter' (8.5x11") or 'a4'
margins: { // Custom margins in points (72pt = 1in)
left: 108, // 1.5 inches
right: 72, // 1.0 inch
top: 72, // 1.0 inch
bottom: 72 // 1.0 inch
},
fontSize: 12, // Base font size (Default: 12)
lineHeight: 12, // Line height in points (Default: 12)
includeTitlePage: true, // Generate title page if metadata exists
showSceneNumbers: true, // Render scene numbers (#1#)
showPageNumbers: true, // Render page numbers in top right
showFirstPageNumber: false, // Suppress page number on Page 1 (Industry standard)
moreAndContinued: true, // Add (MORE) & CHARACTER (CONT'D) across page breaks
moreText: '(MORE)', // Custom text for (MORE)
continuedText: "(CONT'D)", // Custom text for (CONT'D)
printNotes: false, // Print [[ notes ]]
printSections: false, // Print outline sections (#)
printSynopses: false // Print synopses (=)
});📜 Supported Fountain Syntax
| Fountain Element | Example | Notes |
| :--- | :--- | :--- |
| Title Page | Title: MOVIEAuthor: Jane | Placed on page 0 with standard Hollywood layout |
| Scene Headings | INT. ROOM - DAY #1# | Formatted at 1.5" margin with scene numbers |
| Forced Scene Headings| .DAN'S BEDROOM | Any line starting with . |
| Action | He runs to the exit. | Standard 6.0" paragraph wrapping |
| Forced Action | !HE JUMPS. | Any line starting with ! |
| Character Cue | SARAH (O.S.) | Centered at 3.5" (indent 2.0" from margin) |
| Forced Character | @MCINTYRE | Any line starting with @ |
| Dialogue | We need to hurry. | Indented at 2.5" (width 3.5") |
| Parenthetical | (whispering) | Indented at 3.0" (width 2.5") |
| Dual Dialogue | SARAH ^Hurry up! | Side-by-side columns using carets (^) |
| Transitions | CUT TO: or > FADE OUT. | Right aligned |
| Centered Text | > THE END < | Centered across printable width |
| Page Breaks | === | Forces a new page |
| Boneyard Comments | /* comment */ | Ignored and stripped from output |
| Inline Formatting | **bold**, *italic*, _underline_ | Preserved on all wrapped lines |
🧪 Testing
The package includes a comprehensive suite of automated tests covering parsing, text wrapping, pagination, dual dialogue, and PDF generation.
Run on demand:
# Run tests
npm test
# Run type checker
npm run typecheck
# Run test coverage
npm run test:coverageAutomated CI/CD:
- GitLab CI: Runs automated tests on every push and merge request (configured in
.gitlab-ci.yml). - GitHub Actions: Configured in
.github/workflows/ci.ymlwith matrix testing on Node.js 18, 20, and 22.
🚢 Publishing to NPM
The package is pre-configured with prepublishOnly scripts to ensure types, tests, and builds run automatically before publishing:
npm publish📄 License
MIT © rbevers
