@-Mentions & Entity Linking
Link your prose to your story's characters, locations, and other named elements with inline @-mentions that Skribex tracks, indexes, and surfaces across the application.
What it does
When you type @ in the editor, Skribex opens an autocomplete dropdown suggesting known entities. Selecting one inserts a mention chip — a colored inline badge linked to that entity. Skribex tracks every mention across your manuscript, building backlinks, co-occurrence data, and feeding the entity sidebar panel and mind map.
Creating mentions
Manual: type @
- Type
@anywhere in the editor text. - A dropdown appears showing matching entities (searched by name and aliases, prefix-matched).
- Continue typing to filter. Use arrow keys to navigate, Enter to select.
- The selected entity appears as a colored chip with the entity type's color.
If the entity doesn't exist yet:
- Select "create" from the bottom of the dropdown.
- A stub entity is created immediately with the mention text as its name.
- The mention resolves to the new entity in one step.
- You can assign a type and fill in details on the entity page later.
Automatic: Entity Assist
Skribex can automatically detect and link entity names without typing @. Configure the mode from the status bar (@ button — click to cycle through modes) or from the dashboard settings page.
| Mode | Icon | Behaviour |
|---|---|---|
| Off | @ |
No automatic linking. Manual @ only. |
| Discover | @↵ |
On Enter, scans the previous paragraph for known entity names and aliases. Matches are converted to @-mentions with a brief highlight flash. Handles possessives ("Jane's") and simple plurals. |
| Suggest | @… |
As you type, after 2+ characters, a faded ghost-text completion appears inline. Press Tab to accept and convert to an @-mention. Any other key dismisses the suggestion. |
| Both | @✦ |
Discover and Suggest active simultaneously. |
Entity Assist can be set globally (applies to all books) or overridden per book. The status bar button sets the per-book override; the dashboard has both global and per-book dropdowns.
How mentions look
Mention chips are inline <span> nodes with a soft pastel background reflecting the entity type's color. The color is configurable per type from the dashboard.
- Resolved mentions — full color chip. Click to open the entity sidebar panel.
- Unresolved mentions — dimmed chip with a subtle indicator. Click to open the create-entity panel.
In zen mode, mentions can be dimmed (25% opacity, hover to restore) or hidden (appear as plain text) depending on your zen mode settings.
What Skribex tracks
Every mention is indexed on save. Skribex maintains:
| Data | Where it surfaces |
|---|---|
| Backlinks | Entity page — lists every chapter/scene that mentions the entity, with a count per element |
| Mention count | Entity page header, entities overview, sidebar panel, mind map node size |
| Co-occurrence | Sidebar panel "often with" section — entities that appear in the same chapters |
| Viewport entities | Right sidebar Entities section — live list of entities visible in the current scroll position |
Aliases
An entity can have multiple aliases. When any alias is mentioned (via @ or Entity Assist), it resolves to the canonical entity.
- Add aliases on the entity page or when resolving an unresolved mention.
- Aliases are case-insensitive for matching but stored as provided.
- Example: Entity "Aria Voss" with aliases ["The Raven", "Aria"]. Any of
@Aria Voss,@The Raven, or@Ariawill resolve to the same entity.
When the sidebar shows a mention that matched via alias, it displays the alias with the canonical name in parentheses.
Right sidebar — Entities section
The right sidebar's Entities section shows cards for every @-mention visible in the current viewport. It updates live as you scroll.
Compact view (default): entity name, type, mention count.
Expanded view (click a card): aliases, chapter backlinks (click to scroll to that element), co-occurring entities, and a "view page" link.
Clicking an @-mention in the editor auto-opens the Entities section if it was collapsed and expands the relevant card.
Entity page
Click "view page" from the sidebar or the @-mention badge to open the full entity page:
- Name, type, mention count, status
- Aliases (editable)
- Custom profile properties (per entity type)
- Relationships (with add/remove, type filtering, temporal markers)
- Backlinks (every manuscript element that references this entity)
- Link references (smart links pointing to this entity)
- Notes (with tag parsing)
- Markdown description (editable)
Entities overview
Navigate to the entities overview page to see all entities in a searchable, filterable list:
- Search by name or alias
- Filter by entity type
- Sort by name or mention count
- Unresolved stub entities appear in a highlighted section at the top with quick actions
Mind map
The entity mind map (accessible from the dashboard) visualizes all entities as an interactive graph:
- Nodes sized by mention count, colored by entity type
- Edges from explicit relationships, inferred relationships, and co-occurrence
- Right-click context menu for entity actions
- Drag-to-connect to create relationships between entities
- Edge complexity filter: All (everything) / Semantic (explicit + inferred) / Authored (explicit only)
Tips
- Use Discover mode for a first pass through existing prose — it catches entity names you haven't linked yet.
- Use Suggest mode while actively writing — ghost-text completions appear without breaking your flow.
- Create entities early (even as stubs) so that aliases and Entity Assist can find them.
- The mention count is a useful proxy for character importance — check the entities overview sorted by mention count to see who dominates your story.
Notes
- Deleting an entity does not remove existing @-mentions in the manuscript — their backlinks simply no longer resolve.
- Entity types and colors are defined in your book's
types.json(configurable from the dashboard). - Entity files live in
entities/inside your book directory and are versioned in git. - Mentions do not export to EPUB — they render as plain text with the entity name.