Tags and References

In novelWriter there are no forms or tables to fill in to define the characters, locations and other elements of your story. Instead, you can mark your project notes as representing these story elements by creating a tag. Whenever you want to link a piece of your story to a note defining a story element, like a character, you create a reference back to that tag. You can also cross-link your project notes in the same way.

This is perhaps one of the features that makes novelWriter different from other, similar applications. It is therefore not always obvious to new users how this is supposed to work, so this chapter hopes to explains in more detail how to use the tags and references system.

Tip

If you find the Tags and Reference system difficult to follow just from reading this chapter, you can create a new project in novelWriter and select to “Fill the project with example files” in the New Project Wizard. The example project contains several examples of tags and references.

Metadata in novelWriter

The structure of your novelWriter project is inferred from the headings within the documents, not the documents themselves. See Importance of Headings for more details. Therefore, metadata is also associated with headings, and not documents.

If you split your project into separate documents for each scene, this distinction may not matter. However, there are several benefits to using documents at a larger structural scale when starting your project. For instance, it may make more sense to define all your scenes, and even chapters, in a single document at first, or perhaps a document per act. You can later split these documents up using the document split feature. See Splitting and Merging Documents for more details.

The implication here is that you can treat each heading as an independent element of your notes that can be referenced somewhere else. In order to make it possible to reference a header section, you need to assign it a tag.

How to Use Tags

A “tag” in novelWriter is a word or phrase that you define as belonging to a heading. Tags are set by using the @tags keyword. The full format of a tag is @tag: tagname, where tagname is an identifier of your choosing. You can only set one tag per heading, and the tag has to be unique across all documents in the project.

Note

In version 2.2, tags will be made case insensitive, but as of novelWriter 2.1 they are not. You should however avoid using tags that are only distinguished by case.

After the tags have been defined, they can then be referenced in the novel documents, or cross-referenced in other notes. they will also show up in the Outline View and in the back-reference panel when a document is opened in the viewer.

The syntax highlighter will indicate to you that the keyword is correctly used and that the tag is allowed, that is, the tag is unique. Duplicate tags should be detected as long as the index is up to date. An invalid tag should have a green wiggly line under it, and will not receive the syntax colour that valid tags do.

The tag is the only part of these notes that the novelWriter uses. The rest of the document content is there for the writer to use in whatever way they wish. Of course, the content of the documents can be added to the manuscript, or an outline document. If you want to compile a single document of all your notes, you can do this from the Manuscript Build tool.

Example of a heading with a tag for a character of the story:

# Jane Doe

@tag: Jane

Some information about the character Jane Doe.

When this is done in a document in a Root Folder of type “Characters”, the tag is automatically treated as an available character in your project, and you will be able to reference it in any of your other documents using the reference keywords for characters.

It is the root folder type that defines what category of story elements the tag is indexed under. See the Project Roots section for an overview of availabe root folder types. They are also covered in the next section.

How to Use References

Each heading of any level in your project can contain references to tags set in project notes. The references are gathered by the indexer and used to generate the Outline View, among other things.

References are set as a keyword and a list of corresponding tags. The valid keywords are listed below. The format of a reference line is @keyword: value1, [value2] ... [valueN]. All reference keywords allow multiple values.

@pov

The point-of-view character for the current section. The target must be a note tag in a Character type root folder.

@focus

The character that has the focus for the current section. This can be used in cases where the focus is not a point-of-view character. The target must be a note tag in a Character type root folder.

@char

Other characters in the current section. The target must be a note tag in a Character type root folder. This should not include the point-of-view or focus character if those references are used.

@plot

The plot or subplot advanced in the current section. The target must be a note tag in a Plot type root folder.

@time

The timelines touched by the current section. The target must be a note tag in a Timeline type root folder.

@location

The location the current section takes place in. The target must be a note tag in a Locations type root folder.

@object

Objects present in the current section. The target must be a note tag in a Object type root folder.

@entity

Entities present in the current section. The target must be a note tag in a Entities type root folder.

@custom

Custom references in the current section. The target must be a note tag in a Custom type root folder. The custom folder are for any other category of notes you may want to use.

The syntax highlighter will alert the user that the tags and references are used correctly, and that the tags referenced exist.

Note

The highlighter may be mistaken if the index of defined tags is out of date. If so, press F9 to regenerate it, or select Rebuild Index from the Tools menu. In general, the index for a document is regenerated when it is saved, so this shouldn’t normally be necessary.

One note can also reference another note in the same way novel documents do. When the note is opened in the document viewer, the references become clickable links, making it easier to follow connections in the plot. You can follow links in the document editor by clicking them with the mouse while holding down the Ctrl key. Clicked links are always opened in the view panel.

Project notes don’t show up in the Outline View, so referencing between notes is only meaningful if you want to be able to click-navigate between them, or of course if you just want to highlight that two notes are related.

Tip

If you cross-reference between notes and export your project as an HTML document using the Manuscript Build tool, the cross-references become clickable links in the exported HTML document as well.

Example of a novel document with references to characters and plots:

## Chapter 1

@pov: Jane

### Scene 1

@char: John, Sam
@plot: Main

Once upon a time ...