This tutorial assumes readers have some previous beginner-level experience with HTML and Javascript.
Tracery is a tool to generate text, stories, and even images, via text. Itās the creation of Kate Compton, who has worked creating generative art and toys for many years. Compton created Tracery over a decade ago, and itās long been the tool of choice for bot-makers. When I was first wading deep into creating media artworks and later procedurally-generated projects I was enamored with the scene of artistic bots that lived on Twitter. I created several of my own.
V. Buckenham created the web-based tool Cheap Bots Done Quick, which gave a nice web interface to script a bot using Tracery and then to launch it on Twitter. Around the time an evil billionaire purchased that social media product, these kinds of generative artistic bots were prevented from working through an API change, and any folks that remained on this now-irrelevant platform decided to clear out for other less-fashy online spaces. In fact through the power of open source the Cheap Bots Done Quick project has been forked and kept alive through Cheap Bots, Toot Sweet! for Mastodon bots and Blue Bots, Done Quick! for BlueSky.
But aside from botmaking, Tracery can be used in software, websites and games. I wanted to use it to make a simple custom Lorem Ipsum generator. Lorem ipsum is example text you can use as a designer to see how your text will fit on a web page or in a program or in a page of a book for example, named for the latin text often used. There are many easily searchable Lorem Ipsum text generators. Bacon Ipsum, Hipster ipsum are two that immediately come to mind.
I wanted to make my own bespoke retro and shareware-style software description generator to describe the kinds of things I would have found in a cheap bin at the local computer store in the late 90s (well, maybe not), so I made one with Tracery.
Getting started with Tracery
Tracery is a tool to construct grammars. The word grammar here means basic sentence structures. It works very similarly to the classic game of Mad Libs, but instead of just supplying a blank space where you want words filled in, you specify a list of words or even constructions of words to fill in. You create an origin that is the recipe for filling in words randomly. The grammar lives in a json data file.
Hereās a basic example:
{
"greeting":["Hello!","Top of the morning to ya!","The best part of waking up is Folger's in your cup"],
"person":["stranger","sailor","mom"],
"origin": ["#greeting# #person#."]
}
Our program will start at the source. First it will pick a random word from greeting, followed by a randomly selected person word.
If you want to try this code out in the online Tracery Editor you can remove the original code and paste into the editor. Press reroll to see different results.
Tracery also allows us to create more complex grammars, and comes with some nice tooling. You can capitalize a word by adding .capitalize for example. These are called modifiers. Some other modifiers capitalize all expansion words, add s to pluralize a word, or change present to past tense (āedā).
"origin": ["#greeting# #person.capitalize#."]
Often you may want to expand text strings to use further text strings. Hereās an example of that:
{
"greeting":["Hello!","Top of the morning to ya!","The best part of waking up is Folger's in your cup,"],
"person":["stranger","sailor","mom"],
"occurrence":["talking to a #person#"],
"origin": ["#greeting# #person.capitalize#. I couldn't help but notice you #occurrence#."]
}
Which produces results like:
Top of the morning to ya! Mom. I couldnāt help but notice you talking to a sailor.
There are more things that Tracery can do. I recommend you check out the project repo to review it.
Integrating Tracery with a website
If youāre not making a bot and want to produce procedurally-generated text on a website, hereās how you can do it.
Create your basic webpage. At the very least, youāll need to link to Tracery, to your own script, and (unfortunately) Tracery currently requires jquery as a dependency.
<html lang="en">
<head>
<title>My Tracery project</title>
<!-- this is a link to the jquery slim minified library for testing. I personally usually self-host if I publish the project online -->
<script src="https://code.jquery.com/jquery-3.7.1.slim.min.js" integrity="sha256-kmHvs0B+OpCW5GVHUNjv9rOmY0IvSIRcf7zGUDTDQM8=" crossorigin="anonymous"></script>
</head>
<body>
<h1>My Tracery project</h1>
<div id="myTracery"></div>
<noscript>This generative text project requires JavaScript.</noscript>
<script src="js/tracery.js"></script>
<script src="js/main.js"></script>
</body>
</html>
Weāve made a minimal starter website, linked to the jQuery CDN (or self-host), linked to a downloaded version of Tracery in a folder js, and linked to our own custom main.js script also in the js folder.
Hooking up Tracery to our site
We create a js directory in our root folder for our website and download tracery into that directory.
Lastly, create a new text file, which weāll call main.js and place in the js directory.
Hereās some starter code which will hook into our div with the id #myTracery in our html file:
ourText = {
"greeting":["Hello!","Top of the morning to ya!","The best part of waking up is Folger's in your cup,"],
"person":["stranger","sailor","mom"],
"occurrence":["talking to a #person#"],
"origin": ["#greeting# #person.capitalize#. I couldn't help but notice you #occurrence#."]
}
//starts up Tracery
let grammar = tracery.createGrammar(ourText);
//saves output as a string
let s = grammar.flatten("#origin#");
//places that string in our div on the html page
document.getElementById("myTracery").textContent=s;
And thatās the most basic version of using Tracery.
You can see a simple example in my custom Lorem Ipsum Software page. Feel free to view source on it.