Craft

Links and mentions

Files point at each other in three ways. All three store the other file's fixed id, not its name, so renaming a file never breaks a link to it.

Link Where Written as
Reference field A field of a JSON file picked from the field's list of files
Mention The body of a Markdown file made by typing @ and picking a file, shown as a link with the file's name
Map link A pin or area on a place's map Set on the map

Reference fields

A reference field is a schema field that holds another file of a named type: a character's race, a shop's stock, a spell list. Name the other file, and Craft stores the file it means. Computed fields can read through a reference (load($self.race)), layouts show it as a card, and the GM reads it as a link to the file.

  • A value that matches no file yet is kept as a draft and links once the file exists.

The full rules, filters and lists of references are in references.

Mentions

A mention links another file from a page of prose. It is made by typing @ and picking a file.

  • It shows as the file's current name, and follows the file through any rename.
  • Mentions work in a Markdown file's body. In a JSON file, link with a reference field.
  • A mention inside code (backticks or a code block) stays plain text.
  • A mention must point at a file that exists: create the file first, or in the same batch. Unlike a reference, there is no draft.

In the editor, type @ and pick a file to mention it.

A pin or area on a place's map can link to another file, usually a place inside it or a person who is there. The map shows the linked file's current name and picture, and the GM reads the map's links to know what is where. Exits link to the place they lead to. See maps.

When files are copied

A game, a clone of a world and an installed package each get copies of the files, and every copy keeps its fixed id. So a link inside the copy points at the copy, not back at the world it came from. A game's character who mentions the innkeeper links to the game's innkeeper.

When a file is deleted

A link to a deleted file stays saved but leads nowhere: a mention shows as unresolved, and the GM reads it as a removed file. Restore the file from the trash and they lead to it again.