Renaming a tag breaks existing references

[Alok-S-Sharma]

Description

During drafting, I often use abbreviations or temporary names for characters and places to avoid breaking writing flow (for example, referencing a housemaid as HM). Once the scene is complete, I later research and assign the final character name and update the corresponding tag.

In this workflow, renaming an existing tag that is already referenced elsewhere causes all existing references to silently break. The application then reports a missing reference and suggests rebuilding the index, which does not resolve the issue because the original tag name no longer exists.

This makes iterative drafting and later refinement risky, as there is no warning, no automatic update, and no reliable way to detect or repair orphaned references created by renaming tags.

What the bug is

When a tag defined using @tag: is renamed after it has already been referenced elsewhere (for example via @char: in scene files), all existing references to the old tag name become invalid.

Clicking the broken reference shows an error dialog stating that the reference cannot be found and suggests rebuilding the index (F9). However, rebuilding the index does not resolve the issue because the original tag name no longer exists.

This results in orphaned references with no in-app way to detect, repair, or update them, and the recovery guidance provided by the error dialog is ineffective in this scenario.

Steps to reproduce

1. Create a Character note under a Character root folder.
2. Inside the character note, define a tag, for example:

@tag: HM

3. In a scene file, reference the character using:

@char: HM

4. Later, rename the tag in the character note to a final name, for example:

@tag: Sushila Devi

5. Return to the scene and click the existing reference @char: HM.

Rebuild the index using Tools → Rebuild Index or by pressing F9.

Expected behaviour

One of the following (or similar) would be expected:

• Existing references update automatically when a tag is renamed, or
• A warning is shown when renaming a tag that is already referenced, or
• Orphaned references are detectable and repairable, or
• The error dialog does not suggest index rebuilding when the underlying issue is a renamed or missing tag
• At minimum, the application should not imply that rebuilding the index will fix the problem when it cannot.

Actual behaviour

• Clicking the reference opens an error dialog.
• Rebuilding the index (F9) does not resolve the issue.
• The reference remains broken because the original tag name no longer exists.
• The only workaround is manually searching for and updating all references.

Error dialog message

Could not find the reference for tag 'HM'. It either doesn't exist, or the index is out of date.
The index can be updated from the Tools menu, or by pressing F9.

Possible improvement / design suggestion (inspired by Footnotes)

A potential way to avoid this class of breakage could be to internally reference tags by a unique key rather than the visible tag name, similar to how footnotes work.

For example:

@tag[xyz123]: Character Name

Scene references would then bind to the unique key (xyz123) rather than the display name. Renaming the tag text would not break references, since the key remains unchanged.

This is conceptually similar to the existing Footnotes system, where:

• Keys are unique
• Display text can change
• References remain stable

Such an approach would support iterative drafting workflows where temporary names are later refined, without risking silent reference breakage.

Environment:

Operating system: Linux – Zorin OS 17.x
novelWriter version: 2.8.2
Installation method: AppImage

[vkbo]

Generally, the search tool is the way to find and update renamed tags, although there are other ways (see suggestion at the bottom of this reply). The display name feature was also added to allow you to select a different way to display the tag when it is included in the manuscript like in for instance titles.

I do plan to add a panel to navigate meta data in the project. It would be a third view in parallel to project view and novel view. Adding a flag that shows orphaned references shouldn't be too difficult.

One of the following (or similar) would be expected:

• Existing references update automatically when a tag is renamed, or

novelWriter will never update the text of a file automatically after it's created, so this one is a no-go.

• A warning is shown when renaming a tag that is already referenced, or

This one is possible since the tag is evaluated as you type as it already checks for conflict with existing tags of the same name. However, the question is then when exactly to pop up the dialog box telling you that it is in use. It is really annoying to have popup boxes trigger as you're typing.

The editor did use to have a warning banner at the top that would alert you if you were doing something that warranted a warning. That panel was removed at some point because it was not being used for anything any more. I could re-introduce it as a part of the document header.

• Orphaned references are detectable and repairable, or

See comment above. Detectability can be added.

• The error dialog does not suggest index rebuilding when the underlying issue is a renamed or missing tag
• At minimum, the application should not imply that rebuilding the index will fix the problem when it cannot.

The error message implies that it also may not exist:

I can rephrase "The index can be updated ..." to "An outdated index can be updated ..." for clarity.

---

I'd like to also point out that the References panel below the viewer shows a list of all document referring back to the one currently open in the viewer. If you go through the documents and update the references before the tag is changed, this should help. There is an edit button on each entry you can click to open it in the editor, which will not change the viewer panel.

[vkbo]

I also wanted to comment on your suggestion about using keys. These are just some immediate thoughts:

• Manually adding a key (or generating a key on first use) to the tag definition is a little clunky notation. I found no way around it for footnotes, but I'm still not happy with the implementation there either.
• Keeping a key reference internally (i.e. not user visible) is possible as it could keep a map in the index between all iterations of a tag and its key, but it runs into issues if the writer wants to reuse a tag for something else.
• You can actually use semantically meaningful keys that are not names as tags, and then add a display name as suggested in the previous comment. In your example, handmaid could just be the tag. Since it is possible to add a display name to tags, using that display name more in the UI may help improve this too.

The status/importance labels used to have the exact same problem as you describe, and now use a generated key internally. However, this was only possible because the user never has to type it in the document. It's pure project meta data. This is not really possible in the same for the tags since the tags are associated with headings, not documents, and the index itself is not guaranteed to survive an upgrade and cannot be relied on to preserve information.

But there may be a possible solution in treating tags more strictly than they are now and tracking them along the document in the project itself, and mapping them to keys there in a similar way status/importance labels. That way, the project can keep such a map on each document meta data entry in the project file. It would then be able to issue a warning when the document is open that some references are out of date, but not break the reference link itself, allowing you to update documents when you next edit them.

This is a rather complicated solution to the problem though.

[Alok-S-Sharma]

Thank you for the detailed and thoughtful response — that clarifies a lot about the design constraints and why automatic text updates are intentionally avoided.

I fully understand and respect the decision to never modify document text automatically. That makes sense for a writer-centric tool and avoids a whole class of unintended side effects.

From a workflow perspective, the biggest pain point for me isn’t automatic updating, but rather:

• Silent breakage when a tag is renamed
• The inability to clearly detect orphaned references
• The error dialog suggesting index rebuilding when the underlying issue is actually a renamed or missing tag

Even just detectability (and possibly a warning banner or panel indicator) would already go a long way toward making iterative drafting safer — especially for workflows where temporary names or abbreviations are used early and refined later.

I appreciate the explanation around why footnote-style keys are difficult to apply to tags, and I understand that any key-mapping approach would be non-trivial. My suggestion there was mainly meant as a conceptual direction rather than a concrete expectation.

Thanks again for taking the time to engage so deeply with the issue — the clarifications around the References panel and the planned metadata navigation view are especially helpful.

[vkbo]

Even just detectability (and possibly a warning banner or panel indicator) would already go a long way toward making iterative drafting safer — especially for workflows where temporary names or abbreviations are used early and refined later.

Then I propose to keep this request open.

[Alok-S-Sharma]

Thank you for keeping this open — that’s very helpful.

Building on my previous message and still working within the constraint of keeping everything explicitly in the document, I tried a workflow using a stable tag value with a display name, for example: @tag: ln72ov2z | Earth

Conceptually, this works very well:

• ln72ov2z acts as a stable identifier that never changes
• Earth is the human-readable name that can evolve
• Renaming the display name does not invalidate references

However, to make this workflow practical and readable during writing, I see two related UI aspects that would be important.

1. Auto-complete / look-up list behaviour

When referencing this tag in a scene, the auto-complete / look-up list currently shows only the raw tag value (ln72ov2z). This makes it difficult to use, since the identifier is not meaningful to the writer.

Would it be possible that, if a tag has a display name, the auto-complete / look-up list shows the display name instead of (or in addition to) the raw tag value?

For example, the list could show something like: Earth (ln72ov2z) while still inserting the actual tag value internally.

2. Display name visibility in the document and viewer

Once the tag is referenced in a scene using this approach, it would also be very helpful if:

The display name is visibly suffixed or associated with the tag in the editor, so it’s immediately clear what the reference points to.

When viewing the document using Ctrl+R, the display name is shown, not just the raw tag value.

This would keep documents readable while still preserving a stable underlying reference.

3. Display name updates and index rebuilds

This also leads me to a related question:

If I later change the display name of a tag in Locations, Characters, Objects, Entities, etc., will the display name shown in existing references update automatically?

If automatic updating is not desirable (or not possible), then using F9 (Rebuild Index) as the explicit mechanism to refresh displayed names would be perfectly reasonable and consistent with the existing model.

Taken together, this approach could:

• Avoid automatic modification of document text
• Keep tags stable and document-owned
• Support iterative drafting with temporary names
• Preserve readability in both editor and viewer
• Use index rebuilding explicitly where needed

Thanks again for the detailed discussion and for considering these ideas — I really appreciate the care you put into maintaining a clear philosophy while still exploring practical workflows for writers.

[Alok-S-Sharma]

After reflecting a bit more on how novelWriter already stores documents internally, I noticed something that might be relevant to this discussion.

Each document (locations, characters, objects, entities, scenes, etc.) already has a stable, unique internal identifier, for example via the file name and metadata:

%%~name: Mars
%%~path: 15c4492bd5107/5eaea4e8cdee8
%%~kind: WORLD/NOTE
%%~hash: 0838371bc03e31f503fd12a8617d94ef36e5f7c7
%%~date: Unknown/2023-08-25 16:52:07
# Mars

@tag: Mars
@location: Space

It’s red. Dusty and red.

This means:

• Every document already has a unique, stable identity
• That identity exists independently of any @tag: defined inside the document
• This applies uniformly across locations, characters, objects, entities, notes, scenes, etc.

Given that, it seems that a unique identifier already exists at the document level, and there may not be a need to introduce a separate unique identifier system specifically for tags.

This also leads to a related observation:

If documents already have stable identities, then references conceptually point to documents, not to tag strings. In that sense, requiring a @tag: to be defined first in order to reference a location, character, object, or entity feels like an extra indirection layer.

In principle, it seems possible that:

• A location / character / object / entity could be referenced directly
• The reference could resolve to the document’s existing internal identity
• The visible name could remain fully editable without breaking references

I fully understand that this touches deeper architectural decisions, and I’m not suggesting automatic text rewriting or hidden behavior. I’m mainly pointing this out because novelWriter already does a lot of the hard work in the background to uniquely identify documents, and it feels like that existing mechanism could potentially reduce the fragility currently seen with tag renaming.

Even if this doesn’t lead to a change, I thought it might be useful context alongside the earlier discussion about display names, auto-complete, and reference stability.

[vkbo]

As I've already mentioned (I think?) the tags refer to headings, not documents.

See first paragraph: https://novelwriter.io/docs/usage/tags_and_references.html#how-to-use-tags