m. c. de marco: To invent new life and new civilizations...

PrePub

PrePub is a Twine 1 and 2 proofing format for converting simple Twine stories to a flat (Pandoc extended) Markdown file, useful for conversion to EPUB, PDF, or other formats via Pandoc. You will need to install Pandoc, preferably version 2.8.0.1 or later, for the EPUB step.

The PrePub web page is here. You can get a demo EPUB here.

Installation

To add PrePub to Twine 2, use this URL (under Formats > Add a New Format): https://mcdemarco.net/tools/scree/prepub/format.js. Also make PrePub your default proofing format (under Formats > Proofing Formats).

To add PrePub to Twine 1, create a new folder called prepub inside your targets folder, then download this file: https://mcdemarco.net/tools/scree/prepub/header.html and place it inside the new prepub folder. See the Twine cookbook for more information about installing and using story formats in Twine 1.

You should also download prepub.css, especially if you intend to use paragraph numbering or other options, and optionally epub.yaml, some convenient defaults for Pandoc. It’s also handy to try your results out as HTML first, since it’s closely related to EPUB format; for conversion to HTML please use html.yaml to avoid gotchas.

Use

PrePub produces a Twine HTML file that, when opened in a browser, shows you the PrePub options and lets you download its Pandoc Markdown output. To make this happen, do one of the following:

Once you have opened the proofing copy/HTML file, you can select your options and click the download button. This downloads a Markdown file named something like prepub123456789.md.

Details

PrePub converts wiki-style links in your story to implicit header references (part of Pandoc’s Markdown extensions) in the Markdown output. It moves your start passage to the start of the file, if it isn’t there already, and your colophon (i.e., any passage titled StoryColophon) to the end. It removes common special passages but otherwise leaves the passages of your story in place and in order, unless you choose to shuffle them.

Markdown styling is preserved by PrePub and understood by Pandoc. Basic old-style wiki formatting (which is optional in Harlowe and expected in SugarCube) can be removed with the appropriate option, but you may have to manually convert any advanced formatting before compiling to EPUB. HTML may or may not be preserved through the conversion process.

Options

For passage headers, the options include: no passage headers at all, the passage name (the default), sequential numbering, a single character divider, or an image divider.

There is an option to shuffle passages; otherwise the passages appear in the same order in the text as in the source file.

There is an option to convert wiki-style markup (as used in non-markdown-based story formats) to Markdown. You will need to choose the particular story format you used. (If it partially supported Markdown, that Markdown will be preserved.)

After downloading the Markdown file, the PrePub GUI remains open. To select different options, choose the appropriate radio button and/or checkbox, then click Download to get a new Markdown file with a slightly different name.

Making an EPUB

You should use a post-processor like Pandoc to turn PrePub’s Markdown output into EPUB, mobi, HTML, PDF, or other formats. To make an EPUB with Pandoc, type the following at the command line:

pandoc -o my-story.epub prepub123456789.md --epub-chapter-level=2 --toc-depth=1 --css=prepub.css

You will need the prepub.css file mentioned above in order to remove chapter headers or turn them into gamebook-style paragraph numbers. Feel free to add additional styles to the file.

Pandoc supports defaults files, and several have been provided (e.g., epub.yaml) so you don’t need to type out all the recommended Pandoc options. You can pass a defaults file on the command line like this:

pandoc -d epub.yaml prepub123456789.md 

The yaml extension is optional. The defaults include saving the EPUB with the name result.epub; you can change the output file name inside epub.yaml, or you can pass a different output file name on the command line with -o (as in the first example).

Note that --epub-stylesheet has become --css in newer versions of Pandoc, and defaults files are only available in newer versions. It’s also possible to pass Pandoc multiple CSS stylesheets (and defaults files) if you like.

Tweaking the EPUB

Most changes can be made in the stylesheet; you can make the passage headers/numbers/characters/images bigger or smaller there, as well as centering or coloring them as desired.

If you’re going for a continuous paragraph style like in old gamebooks, change --epub-chapter-level=2 to --epub-chapter-level=1 (or edit it in epub.yaml) and remove the line in prepub.css that handles 2-page layouts. Note that such links may not work well in some ebook readers, though they should work in a PDF set to continuous scroll.

Kent Bye lists more flags to set to spiff up your output:

pandoc -o my-story.epub title.txt prepub123456789.md --epub-cover-image=cover.jpg --epub-metadata=metadata.xml --toc-depth=1 --css=prepub.css --css=mySpiffyStyles.css

For help adding more arguments to the Pandoc defaults file, see the Pandoc User’s Guide. For more about producing EPUBs, see Pandoc’s Making an ebook documentation. For styling hints see Blitz ebook Tricks.

Making other formats

You can convert your EPUB directly to Kindle using KindleGen or the Kindle Previewer. (Although Amazon now prefers EPUB to mobi, there is still Amazon-specific formatting to consider; another option for that is Vellum.)

Defaults files for producing HTML or PDF output with PrePub are also available. See the comments in html.yaml and pdf.yaml for the corresponding command line invocation if you need it.

Note that Pandoc may require the installation of additional (usually open source) software in order to produce some output formats.

Examples

The Scree test story is available formatted as markdown using PrePub (test-prepub.md), and as transformed by Pandoc: test-prepub.epub, test-prepub.html, and test-prepub.pdf.

Gotchas

There are a lot of little markup gotchas to using Markdown in general, and Pandoc markdown is no exception.

What it doesn’t do but should (the to-do list)

While EPUB nominally supports JavaScript coding, this support is optional and thus not available in all EPUB readers. PrePub ignores any JavaScript or macros. In addition:

Versions

1.1.2

Add (partial) wiki/custom markup parsing. [Current version.]

1.1.1

Add defaults files and fix minor issues in 1.1.0 for an actual release.

1.1.0

Add some passage header options including shuffling, and move the start passage to the beginning of the story. (Only released on Github.)

1.0.1

Fix line endings in Twine 1 and improve handling of special passages.

1.0.0

Initial version.

Building From Source

Run npm install to install dependencies. Run grunt package to create release versions for Twine 1 and 2 under dist/. Run grunt --help to list other grunt targets.

Sausage

PrePub no longer writes out DOS line endings; you can reintroduce these with Pandoc if you need them.

PrePub can take its options in the query string to help with automation; however, the html file must still be opened in a browser.

PrePub was inspired by enscree, which was based on entwee, which was based on entweedle, but now has a UI more like DotGraph’s.