How to Build a Hypertext Garden with Twine

Jo Suk, New York University

A practical guide for crafting nonlinear narratives using hyperlinked text, based on the How to Build a Hypertext Garden Workshop hosted by NYU Digital Humanities in April 2023.

Introduction

This is a tutorial on how to create a simple hypertext narrative with the open-source interactive fiction tool, Twine. The tutorial is adapted from a library workshop attended by faculty and students from various disciplines. The workshop was created to explore nonlinear narratives using the unique affordances of hyperlinked text.

Background

Hypertext

A hypertext is text that links to other text, usually by way of a hyperlink. The notion of hypertext is not exclusive to web browsers. One well-known analog example of a hypertext is the encyclopedia, which guides readers from the index to the keyword description by way of a page reference. Phone directories, user manuals, and bibliographies are further examples. By comparison, hyperlinks on the web get us from source to destination quicker, and allow connections to branch out infinitely, multi-directionally, and in a less verbose manner.

The Wikipedia Game demonstrates this efficiency by getting players to navigate from one specific page (e.g. Photographic Film) to another (e.g. Rodeo) in as few clicks as possible. The underlying implication is that Wikipedia pages are so interconnected that one can find their way between any two corners through hyperlinks alone.

As a literary form, hypertext falls under what Espen J. Aarseth coins “ergodic literature”, or literature that requires “nontrivial effort” to traverse (Aarseth 1997). In a hypertext, such effort is typically prompted by a hyperlink or set of hyperlinks that one must click in order to proceed through the text. But what follows each click is not purely generative. As they move forward, readers become aware of all the paths they didn’t take, or potential routes that were missing or inaccessible. This “absence of possibility” differentiates a hypertext from traditional linear texts, whose ambiguities are semantic (Aarseth 1997).

Hypertext gardens

The metaphor of a hypertext garden was originated by Mark Bernstein in his 1998 text of the same name. In the text, Bernstein frames hypertext as a literary form that, when arranged carefully, can invoke a pleasurable sense of wandering, akin to walking through a garden. Bernstein writes,

Parks and gardens shape our experience through careful combination of regularity and irregularity. Here we may find beds of flowers -- alike in shape, yet each unique in color or fragrance. Elsewhere, we might break the rhythm of simple geometry with shade trees or hedges, a pond or a boulder. This crafted irregularity engages our senses by offering the promise of the unexpected without the threat of the wilderness. (Bernstein 1998)

The idea here is that gardens are curated and designed to be hospitable. Likewise, a hypertext garden makes executive decisions about the visitor’s path while ensuring their safety and continued wonder. As practitioners, there are a few concrete steps we can take to achieve this, for which we look to digital poet Robert Kendall.

Kendall articulates the qualities of a good hypertext as agency, momentum, and closure. Starting with the first quality, agency, it is clear to see how choosing between a selection of hyperlinks could make one feel involved in a work. However, if the connection between the chosen link and the resulting page is unclear, this can lead to confusion or dissatisfaction on the part of the reader. There should be a clear relationship between the source and the destination in order for the reader to feel properly included.

The second quality, momentum, is not about keeping the reader moving to the point that they become click-happy. Rather, it is about keeping the reader clicking out of curiosity. As Kendall explains,

Maintaining a satisfying balance between continuity and variety in the unfolding text is ultimately what keeps a reader hooked. A work that always yields exactly what is expected becomes predictable and monotonous, while too many surprises and non sequiturs can lead to confusion or even incomprehensibility. (Kendall 1999)

I would also add novelty to the factors that create momentum. According to Kendall, rereading is an essential part of a hypertext reading. Links that send readers to previous passages help them see the winding mechanics of the text, and each reencounter may inspire new understanding.

The final quality, closure, is what leaves the reader feeling like they had a sufficient impact on the text. Without a feeling of closure, the text risks creating tedium. The readers may begin to meander more out of obligation than wonder if they do not perceive their own progress through the garden.

The end of a text can be indicated through any combination of methods, the most obvious being a concluding passage. Some texts contain a visual indicator of the remaining passages to be read. These indicators are visible on each page of the garden and can take shape as a breadcrumb trail, map, or table of contents. Kendall lists Stephanie Strickland’s The Ballad of Sand and Harry Soot as an example of this approach.

Finally, a sense of closure can also emerge from looping passages. However, this effect is delicate, as it is easy for such looping to feel confining. One way to make it feel intentional is to add the final passage as a conditional element whose link only shows after the reader has traversed the same paths a certain number of times.

Twine

When I began preparing this workshop, I was committed to the idea of hypertext gardens early on. Next came the question of how to teach people to build them in one hour. Writing it up in HTML would have been the most natural option, but I worried that we would end up spending most of our time on HTML fundamentals, of which there are many, and many of which would be reckless to rush through. I wanted the participants to have more time to experiment with their connections, so I looked for tools that would facilitate the linking process.

After trying out different web editors and web builders, I landed on Twine as my preferred medium. Created by Chris Klimas, Twine is an open-source tool for building text-based narratives endemic to the web browser. Twine is designed specifically for creating branching hypertexts, so you’ll see that its interface suits the hypertext gardener. The editor contains a visual story map (Figure 1) that not only updates in live time but also makes it significantly easier to understand how passages are linked.

Furthermore, Twine’s linking syntax is much less verbose than standard HTML. In fact, no prior programming experience is required to start building in Twine. The Twine editor features a toolbar to style and add variables to your text without writing any code. The multiple story formats also allow you to build hypertexts with varying levels of programmatic complexity, so there is opportunity to advance.

Though Twine is most widely used for interactive fiction and text-based games, I wanted to show its potential to enrich nonfiction content as well. Among the use cases I found were Christy Tucker’s chat simulation and the Meta-Twine Toolkit created by the Innovative Design for Education and Assessment (IDEA) Lab at the University of Pittsburgh. These examples use Twine to practice making branching scenarios for professionals and instructors in higher education, respectively.

Another example is Suzy Rigdon’s workshop, Using Twine for Nonlinear Storytelling Across the Academic Spectrum. The workshop is designed to help students exercise problem-solving, critical thinking, and academic storytelling by building their own Twine narratives. The presentation contains even more examples of nonfiction Twines that quiz readers on topics like foreign language, Greek gods, and HR-style training.

During our workshop, participants were invited to build in Twine using any topic of their choice. We drew out mind maps before even touching the software, so we could use them as a draft for the Twine work. Most participants drew their mind maps around recent research topics, such as films, elemental computing, and the history of peanut butter.

Using Twine

Setup

Go to twinery.org and either download the desktop app or start a project in your browser. If you plan to work offline, use the desktop app. If you have limited computer storage, opt for the browser editor. The interfaces are identical either way.

If you’re working in the browser editor, it’s important to keep in mind that your stories are saved in the browser’s local storage. This means that: 1) your storage is limited, 2) you will not be able to view your work in an incognito window or different browser, and 3) clearing your browser sessions and cookies will also clear your Twine project storage.

Neither the browser or app automatically enables others to view your story. Sharing your work requires a few extra steps that I’ll detail later. At the time of writing, we were working in Twine 2.0.

Once you’re in the main dashboard, start a new story with the + new button (Figure 2). This takes you to the story editor (Figure 3). In Twine, each story is made up of core components called passages. The official documentation describes passages as “divisions of time, space, or combinations of the two.” You’ll see a sample passage waiting for you in the middle of the screen. Double-click it to open the passage editor.

Linking and preview

Inside the passage editor, you can add the main contents of your passage and begin making connections to other passages. To create a link to another passage, wrap it in double square brackets, [[like so]]. Linking is the quickest way to create a new passage, since Twine automatically creates a new passage based on the name you provide. If the passage you’re referencing already exists, it should show up automatically in a dropdown menu (Figure 4).

To create a link with text that is not the exact passage title, follow this syntax: [[new text->passage name]] or [[passage name<-new text]]. The arrow can point either way, as long as it points toward the passage you are linking.

In case you’re searching for a “save” button at this point—Twine saves your work as you go, so you don’t have to worry about losing progress when you close the tab or app. Again, if you are using the browser editor, be sure to use the same web browser and/or browser profile to access your story, since the data is saved to the browser and not twinery.org.

After creating some new passages and links, you’ll want to see what your story looks like to the visitor. To preview your work, navigate to the build tab and click either test or play to open your story in a new tab. Test opens your story with a debugging menu, while play opens your story exactly as a visitor would see it (Figure 5). Either way, you’ll be able to see your story in its latest form, with clickable links and buttons to move backward and forward.

Story formats

All the work we’ve done so far has been in the default story format, Harlowe. At the time of writing, there are five story formats that come with Twine 2.0: Harlowe, Chapbook, SugarCube, Snowman, and Paperthin. Each story format comes with its own bespoke documentation site, CSS stylesheet, and syntax. This means that the default appearance of your story will vary according to the format. The syntax you use to create interactions and stylize the text will also depend on what format you use. Luckily, the way links are written is the same across all story formats, so you don’t have to unlearn anything we’ve covered thus far. For the purposes of this tutorial, we will continue working in Harlowe.

Before moving on, it’s helpful to have a general idea of what other formats exist and why. To view the available story formats, go to the Twine tab and click story formats (Figure 6). If you don’t plan to add many customizations, you may want to simplify things by using the Chapbook format, which is, according to the reference guide, “designed to be easy to learn and to make many common tasks people have when creating with Twine as simple as possible.” If you want more control over the style and interaction of your story and feel comfortable working in web development languages like CSS and JavaScript, you may want to try out the SugarCube or Snowman formats. If you want to proofread your work, you can switch to the Paperthin format to generate a manuscript-like version of your story. Finally, a more advanced option is to import an entirely new story format. See M. C. DeMarco’s catalog of indie story formats for examples.

To check your story’s current format or switch to a new one, you can go to the story tab, click details, and select a new option from the dropdown menu (Figure 7). Switching your story format will not erase any existing content. However, you will have to update the syntax for any custom styling or macros in your story, since each format addresses these differently.

Basic text styling

You can add basic styling to your text directly in the passage editor, using either markup code or the style menu. If you’re using markdown, you can follow this syntax (keep in mind this is specific to Harlowe):

If you prefer the style menu, you can access it by clicking on the BIS icon next to the color wheel in the passage editor (Figure 8). This opens a dropdown menu of standard CSS text styling options.

Another way to style

Though custom styling is optional, many Twine builders will change the appearance of their stories to coordinate with the story’s premise (e.g. Cecile Richard’s directions chatbot). Some stories rely more on graphics than text to push the narrative forward, which also creates an onus for style updates (e.g. Derek Timm-Brock’s interactive comic The Love Robot).

If you are familiar with CSS, you can style your passages in the stylesheet, which is accessible under the story tag. The styles here will be applied globally (in other words, to every single passage in your story) since each passage consists of the same building blocks. Here you can change the styling of Twine’s bespoke elements, which are usually preceded by “tw-” (Figure 9). For example, you can apply a background image to all of your passages using the tw-story element, which encompasses the entire page. Then you can add a background color to the area immediately surrounding the text using tw-passage to make it more legible against the background image. From there, you might want to change the color of your links to coordinate with the rest of the theme you’re creating, which you can do with tw-links.

Here’s a tip: if you’re looking to style any of the bespoke elements, you can see what each element is called by viewing your story in test mode and clicking on DOM view in the debug menu (Figure 10). This reveals the names and tags of the basic elements, which you can then reference in the stylesheet. To get the names of even more granular elements, like the sidebar buttons (tw-icon[alt] in Figure 9), you can inspect the element using your browser’s developer tools (if you aren’t familiar, MDN web docs has a simple explainer on developer tools).

Interaction

To add more variety to your Twine story, you can use macros. Macros are pieces of code that allow you to add variables, conditions, and custom functions to your story. You can use macros to address the reader by their own name, update a passage’s contents the second time a reader visits it, or show a word or link at random (Figure 11), just to name a few examples. Though these macros are unique to Twine, much of their functionality is similar to JavaScript, so the logic transfers easily.

Interactive elements are the biggest differentiator between the story formats. The syntax and number of available macros varies for each format. For instance, Harlowe has fewer macros than SugarCube since it is designed for newer programmers. If you’re struggling to decide between formats, it’s a safe bet to start by asking yourself what level of interactivity you want in your story.

I won’t go into macros in detail in this tutorial, but there are several places where you can find instructions for how to use them. The Harlowe, SugarCube, and Snowman documentation all include sections for macros. If you’re looking for a more conversational introduction to SugarCube macros, Allison Parrish’s tutorial is a good place to start.

Adding media

Heavy multimedia experiences are not Twine’s strong suit, as the creators admit in the reference guide, but it is still possible and sometimes desirable to include images and sound into your story. Users have discussed at length how difficult it is to link local assets (in other words, files stored on your computer) within a Twine story in the Twine Q&A, but for brevity’s sake, I would recommend you start by linking images that are already uploaded to the web and thus have a URL ready to use.

Generally speaking, you can add images using HTML and CSS. If you are unfamiliar with the syntax for adding images in these languages, you can find clear explanations on reference sites like MDN Web Docs or W3Schools.

To insert an image, place an HTML <img> tag anywhere within your passage where you want the image to appear. The basic formatting is as follows:

Once you add the tag, you can view the story preview to see if it’s been added properly (Figure 12). In addition to width and height, you can adjust the alignment, add text-wrapping, or even use filters on your image using inline style attributes or the CSS stylesheet.

For audio, each story format has its own way of referencing sound files, so it’s best to consult the documentation for whichever format you’re using. More in-depth guides and tools can be found elsewhere on the internet, such as the Harlowe Audio Library, which is designed to make it easier for beginner programmers to use an audio library.

Troubleshooting

As you build, you can use the help button in the top right corner of the editor to access the Twine Cookbook, which contains tips and examples driven by the Twine community. There is also the Twine Reference Guide, r/twinegames, and a number of user-made resources, such as TwineLab. As specific questions and bugs emerge, you may need to use a search engine to seek answers on forums and user-made tutorials. Remember to seek answers applicable to your Twine version and/or story format, as there are significant differences among these iterations.

Completing the Garden

When you’ve created enough branching paths for the reader to wander, wonder, and stumble upon familiar scenes, you can prepare your story for publication. The remaining steps will be to proofread your passages and upload the story to the web.

Proofreading

The Twine editor doesn’t have built-in tools for proofreading. If you want to proofread your work, you can generate a manuscript of your entire story (Figure 13) and save the resulting page as a PDF to your computer using the print command (Figure 14). After that, you can open the PDF in a text editor or pass it by a human editor. Unfortunately, Twine 2.0 does not have an option to save the manuscript as a text file.

You can get the manuscript in one of two ways. The first is by going to the build tab and clicking proof. Your manuscript will open in a new tab automatically. The second is by switching to the aforementioned Paperthin format. Go to the story tab, then details, then select the format from the dropdown menu. When you click test or play, you will see the manuscript.

These methods are a bit long-winded, but I imagine it would take exponentially more steps to program a spellchecker right into the tool. Not to mention, it would make the app a lot bulkier. Hopefully this understanding will give us patience when going about the proofing process.

Sharing your garden

After building your hypertext garden, you’ll surely want to invite visitors to come view your branching body of work. Whether you build in the web editor or desktop app, Twine does not automatically enable others to view your story. In this sense, you can be assured that your story will remain private until you feel ready to share it. However, there are some extra steps you’ll need to take in order to make it public.

First, you’ll have to find a web hosting service to host your story. Websites like Itch.io or Neocities are popular destinations for Twine works. Itch.io is an online marketplace for indie games and interactive fiction that currently hosts over 7,000 projects made with Twine. While Itch.io is designed to help compensate indie game developers, many of the projects on the platform are free to play, so don’t feel forced to put a paywall around your project. Neocities is a hosting service that is known for serving highly personalized sites that feel reminiscent of the early web. On both Itch.io and Neocities, a basic account will allow you 1 GB of storage, which should be plenty for your first Twine project.

Once you have your account set up, the next step is to export your Twine story. Navigate to the build tab and click the publish to file button. This will download your story as an HTML file to your computer. Simply upload this file into a new project on Itch.io or Neocities and you’re good to go.

If you already have experience publishing websites, you might also consider hosting the HTML file yourself. Since the export is a static file, any service that deploys code is sufficient. For my own garden, I uploaded the source code to Github and deployed it via Netlify. Both my repository and the public webpage are viewable online.

If you want to send the story to a closed group of people (i.e. for editing purposes), you can upload the HTML file to a shared drive like Google Drive or Dropbox. The viewers can then download the file and open it in their web browser to view the story. This article is helpful if you’ve never opened an HTML document on your computer before.

Other uses for Twine

Though most people build in Twine with the intent of publishing the result, one could also use it as a personal tool for visualizing and mapping ideas. The editor interface is clutter-free and the gestures are intuitive enough to allow for quick connection building. I find it handy for organizing research for these reasons. The connections I draw between my sources can surface previously unnoticed themes, without giving me the trouble of manually reorienting all the arrows as I add new information. That said, if you’re interested in incorporating this into your research practice, there are other tools better configured for everyday use. For instance, both Obsidian and Roam generate visualizations of the connections between your note pages.

This entry is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International license.