Notes on Screenplay Markdown

August 13th, 2011 | by | screenwriting

Aug
13

(Or, rather, Some Longish and Somewhat Technical Notes on Screenplay Markdown.)

Stu Maschwitz recently wrote about using Markdown syntax for screenplay formatting. Markdown is a text-to-HTML conversion tool for writing for the web, originally designed by John Gruber a few years back and now not uncommon as a formatting aid in online forums and other software.

Stu has since followed up his original post with a more concrete proposal for Screenplay Markdown, or SPMD. (Gruber’s original introduction to Markdown and its syntax is here, but isn’t required reading.)

I like the idea a lot. Ideally it would mean that you could work on your screenplay in any simple text editor, then bring that into your screenwriting software as a properly formatted script. This would be useful primarily on mobile devices, especially since they’re still pretty bad at anything other than plaintext editing.

(I won’t go into detail about how all of this is largely moot if you’re using Fade In Mobile, since that works on iPhone and iPad and Android phones and tablets, and lets you round-trip a screenplay from/to the desktop software with no loss of formatting. Stu wants to be able to export to Final Draft, which I won’t judge him too harshly for, even though Fade In Professional Screenwriting Software does all the page and scene locking and revision management a proper pre-production/production workflow needs, and even exports to Final Draft if you really still want it.)

Much of Stu’s proposal overlaps nicely with John August’s Scrippets (which FI, coincidentally, already supports) in terms of general screenplay layout. Scrippets does a good job of defining the rules for how plain text should be transformed to screenplay layout with no additional formatting, and SPMD follows largely the same reasoning. Screenplay formatting is helpfully rigid enough that it’s easy(ish) to infer from capitalization, punctuation, and spacing whether a given line is supposed to be a scene heading, action, a character name, parenthetical direction, dialogue, or a transition.

The thing that initially caught my attention about using Markdown for plaintext screenwriting was the idea of automatically converting something like “**bold**” (i.e., a word with two asterisks on either side, which is Markdown formatting for boldface text) into bold text in the screenplay. Currently Fade In Mobile uses limited HTML so that typing “<b>bold</b>” accomplishes the same thing — but I’d be surprised if anyone used it because it’s so ridiculously labour-intensive to type on a mobile device.

The questions it raised for me, though, were: (1) How does one represent more complex formatting, say bold-italic, when at least canonical Markdown uses * and _ interchangeably so that **bold** and __bold__ (two characters) are the same thing, as are *italic* and _italic_ (one character)1; and (2) how should literal * and _ characters be handled?

For starters, * and _ being interchangeable in Markdown is unfortunate: it’s unnecessary, requires extra typing for bold, is more prone to programmatic misimplementation, and is potentially confusing to users. Plus it makes bold-italic, what, ***bold-italic***? Stu addresses this by modifying the syntax for SPMD to: *bold*, /italic/, and _underline_. That also means */bold-italic/* and other combinations. Originally I wasn’t happy about breaking syntax with canonical Markdown, despite its shortcomings. That’s because at some point you’re going to want your format to be interoperable with something else. There are Markdown-using applications out there, and if you’ve chosen to do something differently, you’re going to run smack into that one way in which they’re entirely incompatible. Then again, Markdown arguably broke tradition with established (albeit informal) plaintext denotation, where anyone who used newsgroups or email before rich text knew that *this* was bold and _this_ was underlined. Plus I’m less concerned, personally, with cross-application compatibility than I am with screenwriting usability. So I’m with Stu on this one.2

Markdown does have an answer for handling literal * and _, but I don’t like it. If you want * to be just an asterisk and not the start of bold text, you escape it. You what it? Escape it. What does that mean? You put a backslash in front of it. One of these: \. As Stu puts it:

If you need to use any of the emphasis characters, you escape them using the Markdown convention of a backslash:

Steel enters the code on the keypad: *\*9765\**

Believe it or not, that turns into:

Steel enters the code on the keypad: *9765*

It’s the “believe it or not” that probably makes my point best. Programmers escape things. Programmers do lots of things that good, decent people should never have to do. Writers shouldn’t have to type something that looks like a regular expression just to make an asterisk.3

Now, granted, these are edge cases, but making sure you handle edge cases properly is important if you want a format to be both robust and usable. On one hand, the number of asterisks and underscores in the average screenplay is pretty low, so maybe it is easier to teach people to type the backslash in order to get all the other benefits of SPMD. They’ll probably learn quickly enough when their waitress character says “bacon/ham/sausage” as “baconhamsausage”, anyway. SPMD could specify that an unmatched / is handled literally, so that, say, “either/or” doesn’t produce any unintended effects. But that doesn’t prevent “It’s win/lose…an either/or situation” from turning into “It’s winlose…an eitheror situation”, and we’re back to making the writer escape the forward slash. I still think a format like this should serve the writer instead of making the writer adapt to it, but I don’t currently have any better ideas. Maybe someone else will.4

Stu also proposes markup (or, rather, markdown) for title pages and dual dialogue: things that are less on my radar.5 A completely plaintext screenplay format is a nice idea, but having garnered a little experience in screenplay formats over the last while, I suspect it will remain an interim format. That’s because when it comes to screenwriting software, making something look like a screenplay is the easy part — there are plenty of programs that will do that, to varying degrees of success. The hard part, the part that keeps the professional industry using only a couple of programs, is all the page/scene/revision locking and management that are an absolute necessity during pre-production and production. It means storing a lot of unfriendly metadata to keep things in the right place and numbered correctly. Anyway, if the format is necessarily going to be an interim one, being able to specify something like a title page becomes less important — to me, that is, at least for the time being. (Caveat: I may be completely wrong, and if SPMD ultimately develops a clean and simple way to do all the dirty work, Fade In will be the first to adopt it as a primary format.)

I’d actually rather see SPMD incorporate the ability to specify metadata like notes, something both Fade In and Final Draft implement as virtual Post-Its. Descriptive scene metadata in the form of Fade In’s synopsis or Final Draft’s scene properties might also be useful. Maybe some variation on: “[[Here is a note]]” or “{{Here is a scene synopsis}}”. Or something like that.

As an aside, I wonder if John August and Nima Yousefi have at least one eye on SPMD. Given the general overlap between SPMD and Scrippets, it would be nifty if Scrippets would support things like *bold*, /italic/, and _underline_, too. (Although knowing next to nothing about the layout engines for the various platforms for which Scrippets is available, I have no idea about the technical degree of difficulty involved.)

Anyway, I expect I’ll be implementing SPMD as soon as things get locked down.


Update 8-Sep-11:
Stu has amended the spec to use ** for bold and * for italic. So yes, ***bold-italic*** it is, which will be fine, and anyway if you’re accustomed to writing everything in 12-point Courier, it really is ***that exciting!***


  1. XHTML puritanism would at this point require jumping up to point out that “bold” and “italic” are deprecated: they’re called “strong” and “emphasis” now. And there’s no such thing as “underline” in XHTML strict itself.
  2. And it doesn’t matter that Markdown has no concept of bold-italic or underlining just because XHTML strict doesn’t: we’re talking about real-world application in visual, printed/displayed material. Which is another argument against deferring to canonical Markdown for formatting: it and SPMD are intended for completely different end-uses, Markdown for producing formatted XHTML and SPMD for producing formatted screenplays. In fact it’s the goal of XHTML to abstract textual communication to the point where application-specific formatting — like underlining — falls outside its spec. That’s why XHTML lets CSS handle things like underlining, which is a level of complexity one probably wants to avoid in something like SPMD.
  3. Markdown does say that if you have a standalone asterisk with a space on either side, it gets treated as a literal, not as formatting. That, however, falls into the about-to-be-discussed category of forcing the writer to write/not write a certain way.
  4. It’s also probably worth pointing out that the problem of accidental misformatting is partly mitigated by a WYSIWYG (or WYATSIWYG — What You’re About To See Is What You Get) editor. That is, a screenwriter will be able to see the formatting go wrong, but he or she may not be any less irritated by it.
  5. I truly wonder if anyone, having been previously unaware of dual dialogue, has ever thought, “Man, I really need to do some sort of dual dialogue in my script,” then went hunting for the way to do it — as opposed to finding out that the software can do dual dialogue and thinking, “Man, that’s neat, I’m going to come up with somewhere I can use that.”

Authored by

Comments are closed.

© 2014 Kent Tessman

▲ Back to top