Versioning comic scripts using Fountain and GitHub
I’m sold on this workflow, jump to the tutorial!
Why this workflow?
I write comic scripts in Fountain, an open-format filetype for scripts and screenplays, and export them to PDF to send to my collaborators (artists, coauthors, publishers).
Previously, each new draft would result in a sheepish email to everyone involved, asking them to please ignore the previous draft and see bullet points below for the summary of changes. This was untenable.
I wanted a workflow that enables my collaborators to:
- inspect the exact, line-by-line edits between any two drafts; and
- access the latest version of the script in PDF,
while I write and overwrite the same single file all throughout (i.e., none of this).
In short, I wanted to implement version control.
The workflow I settled on is straightforward: I push my .fountain
script files to a GitHub repository, then use ’afterwriting, an open-source Fountain converter, to automatically keep the PDF versions up-to-date.
Requirement (1) is satisfied because Fountain files are plaintext, and thus compatible with GitHub’s compare (diff
) feature. Requirement (2) is satisfied because ’afterwriting has a command line interface that can be automated with GitHub Actions.
When all is said and done, the repo looks something like this:
Why use Fountain?
Fountain is a formatting convention for writing scriptlike documents. Here is a comic script written in Fountain:
# Page 1
.Panel 1
It's dark. A coffee cup in the foreground. In midground, ALYSSA on the phone.
ALYSSA
*Uh-huh...*
Fountain is free. Like Markdown, Fountain files are nothing more than plaintext files saved with a .fountain
extension. Unlike Final Draft, Word, or Google Doc files, which require costly 1 and proprietary software to view and edit, .fountain
files can be read and edited on literally any computer.2
Fountain is futureproof. Proprietary software may force strongly encourage you to upgrade to the latest version or change your file formats, but your computer will always have a text editor. This makes Fountain ideal for storing scripts without worrying about software obsolescence or incompatibilities.
Fountain exports to the usual file formats. While plaintext Fountain already looks rather “script-like,” free converter software can parse the special formatting rules3 into a nicely-rendered PDF:
(If you must, Fountain also exports nicely to Final Draft.)
Setup
- Make a GitHub account, create a new private repository, and clone it to your local computer. Let’s call this folder
my-script-repo
. - Open a text editor.4 Create a text file called
.gitignore
inmy-script-repo
containing:.DS_Store desktop.ini
- Move your Fountain script file into
my-script-repo
. Let’s call itscript.fountain
. - Create a text file called
config.json
inmy-script-repo
containing:{ "embolden_scene_headers": true, "show_page_numbers": true, "split_dialogue": true, "print_title_page": true, "print_profile": "a4", "double_space_between_scenes": false, "print_sections": true, "print_synopsis": true, "print_actions": true, "print_headers": true, "print_dialogues": true, "number_sections": false, "use_dual_dialogue": true, "print_notes": true, "print_header": "", "print_footer": "", "print_watermark": "", "scenes_numbers": "none", "each_scene_on_new_page": false }
This config file customizes the PDF output generated by ’afterwriting. Customize these settings as you like; refer to the documentation for a complete list of available settings.
- Create a subfolder
my-script-repo/pdf
. Inside it, create an empty text file called.gitkeep
. - Add, commit, then push this first set of changes to GitHub. (For help, see here.) At this stage, your folder structure should look like:
. └── my-script-repo/ ├── .gitignore ├── script.fountain ├── config.json ├── pdf/ │ └── .gitkeep └── .git/ └── << ignore these files >>
- Go to
my-script-repo
on GitHub. Click onActions
>New Workflow
. - Click on Simple Workflow >
Configure
. -
Rename the file from
blank.yml
tofountain_to_pdf.yml
. Replace the contents of the text box with:name: fountain_to_pdf on: push: branches: - main workflow_dispatch: jobs: convert_files: name: Convert Fountain to PDF runs-on: ubuntu-latest permissions: contents: write steps: # Check out your repository - uses: actions/[email protected] # Install 'afterwriting - name: Install 'afterwriting run: npm install afterwriting -g # Invoke 'afterwriting to export script.fountain to script.pdf - name: Generate PDF run: afterwriting --source script.fountain --pdf pdf/script.pdf --overwrite --config config.json # Commits changes - uses: stefanzweifel/[email protected]
If you have multiple
.fountain
files, theafterwiting --source ...
command must be invoked separately per file. For example, if you have three chaptersC1.fountain
,C2.fountain
, andC3.fountain
, replace the appropriate lines above with:# Invoke 'afterwriting to export script.fountain to script.pdf - name: Generate PDF run: | afterwriting --source C1.fountain --pdf pdf/C1.pdf --overwrite --config config.json afterwriting --source C2.fountain --pdf pdf/C2.pdf --overwrite --config config.json afterwriting --source C3.fountain --pdf pdf/C3.pdf --overwrite --config config.json
where the vertical delimiter
|
indicates that GitHub should run multiple commands instead of just one. -
To the upper right of the text box, click
Start commit
>Commit new file
. - Pull the changes to your local machine. Your folder structure should now look like:
. └── my-script-repo/ ├── .gitignore ├── script.fountain ├── config.json ├── pdf/ │ └── .gitkeep ├── .git/ │ └── << ignore these files >> └── .github/ └── workflows/ └── fountain_to_pdf.yml
Setup is complete!
Update your script
At this point, your pdf/
subfolder is still empty, as you haven’t pushed any new commits yet. Let’s do that now.
- Make some edits to
script.fountain
. - Add, commit, and push the edits to GitHub.
- Allow the workflow to run. You can track its progress on GitHub, under
Actions
. - Once the workflow has completed, go back to your local and pull changes from GitHub. A new file
script.pdf
should now appear under thepdf/
subfolder.
If you don’t want merge conflicts (and you don’t), always pull the newly-updated PDF after every push!
Congratulations!
At this point, the workflow has been set up and you know how to update your scripts. Now your collaborators can see the latest edits for a given file by clicking on its latest commit:5
which leads them to a page with line-by-line comparisons:
Your collaborators can also view the latest PDFs by going to the GitHub website or by pulling the latest changes to their local repo.
Contribute
This walkthrough last worked for me in May 2022. If you spot errors, vulnerabilities, or potential improvements, please do open a pull request on this blog post!
Acknowledgements
This tutorial owes a deep debt of gratitude to Piotr Jamróz and the rest of the ’afterwriting team. (So do I!)
Footnotes
-
While Google Docs is technically free, a stable internet connection is not. ↩
-
Free Fountain-specific scriptwriting apps with syntax highlighting and other quality-of-life features are also available, such as Beat (Mac) or Trelby (Windows, Linux). ↩
-
For instance, section headings begin with
#
; scene headings begin with.
; character names are in all caps. Read the full syntax guide here. ↩ -
Every operating system has one by default, e.g., Notepad on Windows, TextEdit on Mac. ↩
-
Read the GitHub documentation for more ways to compare commits. ↩