Skip to content

Keep an entity's facts in its own file

Nerthus.Core (until cutover). This page describes the frozen system that runs today and is deleted at cutover. Replaced by: not yet written.

By default an entity's facts sit on its entry in the index. They can sit at the top of the entity's own file instead - right above the prose they describe. One place to edit instead of two.

This is optional, it is decided per entity, and an entry with everything inline stays correct forever. Reach for it when you find yourself editing the index and the entity's file in the same breath, over and over.

The move

The index entry points at the file with a - @ref: line, and the facts move into the file.

Before - everything on the index entry:

### Opat Perrin
- @typ: NPC
- @alias: Perrin
- @lokacja: Ithan (:2026-06)
- @lokacja: Thuzal (2026-07:)
- @grupa: Gildia Teologów (2020-01:)
- @status: Aktywny
- @plik: /Postaci/NPC/Thuzal/Opat Perrin.md

After - the entry points at the file:

### Opat Perrin
- @typ: NPC
- @ref: /Postaci/NPC/Thuzal/Opat Perrin.md
- @status: Aktywny
- @plik: /Postaci/NPC/Thuzal/Opat Perrin.md

and Postaci/NPC/Thuzal/Opat Perrin.md now begins:

- @alias: Perrin
- @lokacja: Ithan (:2026-06)
- @lokacja: Thuzal (2026-07:)
- @grupa: Gildia Teologów (2020-01:)

## Reputacja
Przełożony Gildii Teologów w Thuzal...

@ref and @plik are not the same line

They often name the same file and they mean different things:

  • @plik is where the entity's sessions are copied to.
  • @ref is where the entity's facts live.

An entity can have one, the other, both, or neither. Both pointing at one file is the common case, and it is why the two lines look redundant when they are not.

What stays on the index entry

The entry itself, its type, its status, and every line the tool writes on its own. That is why the example above keeps @typ, @status, and @plik on the entry and moves only the facts you author - the alias, the places, the group.

The first heading ends the list

The fact list reaches from the top of the file down to the first heading. From the heading on, the file is ordinary content - write there whatever you want, the tool does not read it.

So the list has to be the first thing in the file, before any prose, and a heading closes it for good.

Dated values work the same

The (from:to) ranges mean the same thing at the top of the file, and close-and-append is the same gesture there. The two @lokacja lines in the example are Opat Perrin's usual timeline, just living in his file.

Where to edit, once you have moved them

Open the file named in the - @ref: line and correct the list at its top. Do not state the same fact on the index entry too.

What happens if you do depends on the kind of fact:

  • A fact that holds one value at a time - the location, say - takes the file's value, and the duplicate on the entry is reported to you as a mistake.
  • A fact that collects many values - @alias, @grupa - reads both places as one list. That is how lines the tool writes onto the entry keep counting.

Your own edits belong in the file either way.

Mistakes are loud, not fatal

If the file goes missing, or the list at its top stops being readable, the tool reports it as an error and the entity keeps working with what stands in the index. Nothing disappears quietly, and nothing about the entity breaks while you fix it.

Adding an entity stays index-first

A new entity is still created in the index, exactly as Add and edit entities describes. The - @ref: line is optional and comes later, when you want the facts next to the prose.