How does novelWriter handle comments, synopsis, and cross-referencing?

novelWriter uses a markdown-like meta data syntax embedded directly in your plain text files. Comments, synopsis, and cross-references are written as special lines that the editor recognises and indexes, while the underlying files stay readable plain text. This means your notes and structure live alongside the manuscript rather than in a separate database, so the project remains portable and robust.

The meta data syntax

Meta data is written on lines that begin with a % character followed by a keyword. Because these lines are just text, they survive copying, syncing, and version control without corruption. The editor parses them to build an internal index of your project.

A typical meta line looks like this:

%Synopsis: The protagonist discovers the letter.

The keyword after % tells novelWriter what kind of information the line carries. Everything after the colon is the content.

Comments

Comments are notes to yourself that should not appear in the rendered manuscript. They use the % prefix so the editor can distinguish them from prose.

% A quick note about why this scene changed.

You can also use a keyword form for structured comments:

%Comment: Check the timeline here.

Because comments are ordinary text lines, they remain visible if you open the file in any other editor — nothing is hidden in a binary format.

Synopsis

Synopsis lines summarise what a document or scene contains. They are useful for outlining and for navigating a large project of many small files.

%Synopsis: Mara confronts her brother about the inheritance.

The synopsis is stored in the same file as the text it describes. novelWriter can collect these across the project so you can review your structure without opening every document. This is the main mechanism that makes a project of many small plain text documents manageable.

Cross-referencing between files

Cross-references let one document point to another by a tag or identifier rather than by file path. You assign a reference tag to a document, then cite it from elsewhere.

%Tag: mara-letter

Elsewhere, you reference it:

%See: mara-letter

The editor resolves these links through its index, so you can jump between related files. Because the link is stored as text, the reference remains meaningful even outside novelWriter — though only novelWriter will resolve it automatically.

Why plain text matters here

The trade-off is that you must follow the syntax conventions for the editor to recognise your meta data. A mistyped keyword is simply treated as ordinary text, so nothing breaks — but the feature won't activate for that line either.

Practical workflow

1. Write your manuscript as plain text documents, one per scene or chapter.
2. Add a %Synopsis: line at the top of each document to describe its content.
3. Add a %Tag: line to give the document a stable identifier.
4. Use %See: or similar reference lines to link documents together.
5. Use % comment lines for reminders that shouldn't appear in the output.

The expected result is a project where structure, notes, and links are all stored in the same plain text files as the prose, and novelWriter's index lets you navigate that structure without leaving the editor.

Common pitfalls

• Forgetting the % prefix. Without it, the line is treated as manuscript text and will appear in your output.
• Reusing tags. Reference tags should be unique, or cross-references become ambiguous.
• Assuming other tools resolve links. The cross-references are meaningful to novelWriter's index; another editor will show them as plain text.
• Editing meta lines in a word processor. Formatting tools may alter the characters and break parsing — keep meta data in plain text.

novelWriter is Free and Open Source and runs on Linux, Windows and MacOS, so the same plain text project can be opened across platforms.