Creating a Story Codex/Bible in Scrivener

Wish I'd known about this ten years ago.

Scrivener continues to be my favorite writing program, but it has a helluva learning curve. I’ve made several attempts to read the manual, but I suspect that, like most people, I give up on it because it’s so complicated, or I just use it as needed when I have a problem.

Today, I’m going to share with you the latest “OMG, I wish I’d have known this ten years ago” moment in the hopes that you find it useful as well. Yes, I’ve been using it that long. Yikes!

When I talk about creating a codex, what I mean is some form of back matter intended for the reader as a reference. I do not mean a wiki that might have highly detailed entries about everything over the course of a book or series. I mean entries for the reader who might want a quick reminder about who a spear-carrier is or a quick clarification on whether the name “Brilles” refers to a star or a planet, that kind of thing.

I guess a codex is like a list of dramatis personae and also a glossary. But not a wiki. I’m very adamant about this not being a wiki, because those would need constant updating and maintenance. A wiki would also have detailed character descriptions, maybe even images. I discourage those kinds of things as back matter because not only does it up the overall size of the manuscript, but it tempts writers not to worldbuild in the story itself, which makes for lazy writing.

As an example, let’s say that in Chapter 20 in the story, you reveal that Jonas is a vampire. In a wiki, you’d document that in Book 4, Chapter 20 or on a certain date, it was revealed that Jonas was a vampire. In a codex entry (dramatis personae) that datum would be omitted because it’s a spoiler.

I started building a codex for RoH4 because I thought it would be pretty easy/fast to do. After all, I wasn’t going for a wiki. Mostly I just wanted to do a list of Houses with a few bits of information like their sigils, colors, and political affiliations. Even though those bits of data are in the story itself, I have a lot of Houses in this one.

The codex-building just kinda snowballed from there.

I have a codex started in Notion, which is more akin to a wiki, for my own use. It’s a bit of a PIA to keep up and I’m not as good about it as I’d like, but here we are.

What we’re going to cover today is how to set up internal links, how to organize them, what the limitations are, and how to set up these entries into a publishable codex that can be used either as back matter during compile, or as a reader magnet.

First, let me show you how your binder needs to be setup for any of this to compile as back matter. You have to set up the folder “Codex” to be on the same level as your Manuscript or Draft, i.e. the folder where your story’s scenes and chapters reside:

The reason we have to do it this way is that the Compile function will have to look at it and use it a certain way.

Let’s say we have a codex entry for the term “avatar” which is used in a particular way in this story.

Abeyance ( the reader's willingness to trust that something they don't understand will be made clear later) is opened in this paragraph for what this term actually means. Abeyance is a tenet of science fiction and fantasy, something that genre readers understand as a given, i.e. we are not expected to understand everything up-front.

You, as the writer, will close/satisfy this abeyance via your worldbuilding, preferably by showing the reader what you actually mean when you use the term. But, as a writer, you may also want to create something for yourself, like that codex or wiki entry, in your manuscript.

You can select the word or phrase, right click, and when you do, you’ll have the option to either create a new link (internal to this document or external as in linking to another document) or to link it to an existing entry. In this case you can see that I’ve already created a Codex entry for avatars, so I’d select that:

Once you’ve successfully linked to the codex entry, you’ll get a blue hyperlink reformatting of the linked text, and if you click on it, it’ll bring up the Codex entry itself:

When you compile, the hyperlink will not be there to confuse your reader because you’ll have unchecked the “Remove all hyperlinks” box before you compile.

If you want to keep the hyperlinks, I guess you can, but I’ve never compiled with that active and can’t tell you if it works as you think it does or should. Maybe something for future investigation, I don’t know.

Even though Scrivener uses markdown files, the next instance of the word “avatar” is not automatically associated with the file we just linked to, just to be clear.

This automatic linking was a feature I was hoping for, but alas, such is not the case.

If you want to have the ability to “auto”-link it, you have to do something else. Open up your settings and make sure that the “Automatically detect [[document links]]” checkbox is checked.

Unfortunately this is not enough to do what I was hoping it would do, which is hyperlink all instances of “avatar.” You have to type double brackets on each side of the word.

Yes, I’m still a bracket short, but that was because otherwise I couldn’t screenshot the change before Scrivener automatically updated it (see below):

Do note that I had to redo the A to lowercase in the title of the linked document because otherwise the blue hyperlink was capitalized as well, which would show up as a capitalized word in the manuscript. I obviously don’t want this, therefore I changed it, so be aware of this matching requirement.

The utility of this type of linking is limited because who wants to have to do the linking for every instance themselves? I’m going with no one, but I think it can still be useful to you for when a term, person, or place is first introduced in the story.

To remove a link, you just select the word or phrase, right-click, and select “Remove link.”

I had about 4,200 words in my Codex, mostly organized by letter, like this, before I realized that I could do it via links. About the only good thing about doing it this way was that I could use the “Edit—>Sort—>Ascending” menu item to keep the list in alphabetical order.

So guess what I’ll be doing now? Yup, I’ll be separating these out using the “Documents—>Split at selection” menu item so that each one is its own entry in the Codex. There is no sort for the folder that B will become, so you’ll have to manually sort any new entries and keep them sorted. Boo. Hiss.

It’s almost better to keep going with one text document per letter, keep it sorted, and then split them and link them back to the first instance or use of the entry. Why can’t I have a program that does everything I want? Why, why, why?

Which brings me to using the character- and place-sketches native to Scrivener. I do not like them, but if you do, and you want to use them in the Codex, you’ll have to move them into the Codex folder. If you leave them under Characters or Places, then they won’t be compiled into the back matter.

Nowhere in my manuscript, do I use “Bhanot, Neria” and since there are multiple entries for Bhanot, I can’t link to Bhanot at all. Again, rude.

I went ahead and split the text document with the B’s and set up Neria as its own separate entry:

We do however now have the problem that the B folder contains an item titled “Neria,”making keeping the sort order even harder.

But, because I used just “Neria” I can link to it from the first instance of her name using the “Link to Document” menu item or by putting square brackets in around “Neria.”

In order to see the output, I did ask it to compile just the A folder in the Codex:

The output looks like this:

Yes, I’m aware of the typo and do keep in mind these are draft entries. I have not had the chance to go over them and edit them properly.

The output looks like it will need a tweak to have a header for each letter, and so on, but those can be set up when compiling (which I didn’t have the time or desire to do just for a demo; sorry).

These kinds of Codex entries, especially if more detailed like for a Wiki, can help keep the details of your world straight, but they are an investment of time. Yes, I’m aware of World Anvil and have used it in the past, but didn’t care for the cost. I’ve really come to loathe subscriptions and how they lock your data on their servers, and yes, that includes when you can export them because they all get exported in shitty formats like html and the metadata gets flattened. Notion is another option that is still free. So is Obsidian, but the Notion interface is easier, better, and frankly, sexier, than Obsidian so it’s winning.

I also spent a lot of time trying to use LLMs to create these codex or wiki entries for me, all with epic fails due to the generative nature of LLM output. It made stuff up even when told not to, often adding details that were not there, not using details that were there, and conflating people, places, and events.

It takes longer to hunt down the details an LLM generates and confirm them than to do this yourself. Yes, it’s slow going, and should be done only at the end, in order to ensure data integrity. Otherwise you’ll edit a detail in the manuscript and forget to update it in the Codex and then you’re screwed. Ask me how I know, I dare ya!

I do wish I would have known about this ability to create bespoke back matter and in-manuscript hyperlinks when I first started writing. I would have created a wiki as I went, and a wiki is easier to parse down to a codex than the other way around.

One feature I wish it did have is the ability to track changes, as in alive or dead status based on which book we are in, or chapter, and so on. It can be manually entered of course, one just has to remember to do it. Sigh. This is what we need non-generative “AI” for, this mundane, mind-numbing BS.

Yes, we need Chaucer even more.

Thank you paid subscribers. To access articles that are more than four weeks old, please consider upgrading to a paid subscription.