Narrative Editor
The Narrative section of a model item gives you a rich text canvas to document your architecture in depth. You can write prose, embed diagrams, add images, include code samples, and link directly to other items in your model — all in one place.
Not every model item has a Narrative section. The Narrative tab only appears on item types that support it.
Accessing the Narrative
Open any model item and click the Narrative tab. In read-only mode the content is displayed without editing controls. To make changes, you need to request edit access (see below).
Entering Edit Mode
The narrative uses an edit lock to prevent two people from overwriting each other’s changes. Only one person can edit a narrative at a time.
To start editing:
- Click the Edit button in the floating toolbar at the top-right of the narrative.
- ArchRepo acquires an edit lock on your behalf.
- The editor becomes active and you can start typing.
If another user currently holds the lock, the toolbar shows who is editing. You will not be able to request the lock until they finish.
To stop editing, click the Done button. Your changes are saved and the lock is released.
The editor auto-saves your changes every 30 seconds while you are in edit mode. You can also save manually at any time using the Save button in the toolbar.
Editing Basics
The narrative editor is block-based. Every paragraph, heading, list, or embedded element is a block. You interact with blocks individually.
Adding content
- Click anywhere in the editor and start typing to add a paragraph.
- Press Enter to create a new block below the current one.
- Press Backspace at the start of an empty block to remove it.
Rearranging blocks
Every block has a drag handle that appears when you hover over its left edge. Drag the handle to move the block to a new position.
You can also use the handle menu (click the ⋮⋮ icon) to:
- Delete the block
- Duplicate the block
- Turn into a different block type (e.g. convert a paragraph to a heading)
Selecting and formatting text
Click and drag to select text, or use Shift + arrow keys. A formatting toolbar appears above the selection with options for:
| Format | Shortcut |
|---|---|
| Bold | Ctrl/⌘ + B |
| Italic | Ctrl/⌘ + I |
| Underline | Ctrl/⌘ + U |
| — | |
Inline code | — |
| Text colour | — |
| Highlight | — |
| Link | Ctrl/⌘ + K |
Changing Paragraph Styles
You can change the style of any block — for example, turning a paragraph into a heading, or a heading into a bullet list item.
Using the slash command: Type / at the start of a line, then type the style name (e.g. /heading 1).
Using the block handle: Click the ⋮⋮ drag handle to the left of a block, then choose Turn into and pick a style from the list.
Available styles:
| Style | Description |
|---|---|
| Paragraph | Default body text |
| Heading 1 | Large section heading |
| Heading 2 | Medium sub-section heading |
| Heading 3 | Small sub-heading |
| Bullet List | Unordered list item |
| Numbered List | Ordered list item |
| Check List | Tick-box list item |
| Quote | Indented block quote |
| Code Block | Syntax-highlighted code with language selection |
| Table | Structured data table |
Slash Commands
Typing / anywhere in the editor opens the slash command menu. Start typing after the / to filter the list.
Press Enter or click an item to insert it at the current cursor position.
Built-in commands
These are standard BlockNote commands available in all narratives:
| Command | Description |
|---|---|
/paragraph | Plain body text block |
/heading 1 | Large heading (H1) |
/heading 2 | Medium heading (H2) |
/heading 3 | Small heading (H3) |
/bullet list | Unordered list item |
/numbered list | Ordered (numbered) list item |
/check list | Tick-box / to-do list item |
/table | Insert a table |
/code block | Syntax-highlighted code block |
/quote | Block quote |
ArchRepo custom commands
These commands insert specialised blocks that are unique to ArchRepo:
| Command | Aliases | Description |
|---|---|---|
/Draw IO | draw, drawing, drawio | Embed a Draw.io diagram — see Draw IO Block |
/Image | image, photo, picture, upload, img | Upload and embed an image — see Image Block |
/Entity | entity | Embed a dataset entity definition — see Entity Block |
/Model Item Link | modelitem, link, model | Link to or embed another model item — see Model Item Link Block |
/Figma Prototype | figma, prototype, mockup, design, wireframe | Embed a Figma prototype — see Figma Prototype Block |
/Mermaid Diagram | mermaid | Write and render a text-based diagram — see Mermaid Diagram Block |
/Callout | callout, note | Insert a highlighted note callout — see Callout Block |
/Info | info | Insert a blue info callout — see Callout Block |
/Warning | warning, caution | Insert an amber warning callout — see Callout Block |
/Error | error, danger | Insert a red error callout — see Callout Block |
/Success | success, tip | Insert a mint/green success callout — see Callout Block |
Custom Block Sub-pages
Each custom block has its own page with full details on how to use it:
- Draw IO Block — embed interactive Draw.io architecture diagrams
- Image Block — upload and display images inline
- Entity Block — show a dataset entity schema with relationships and sample data
- Model Item Link Block — reference another item in the model, with multiple display styles
- Figma Prototype Block — embed a live Figma prototype or design mockup
- Mermaid Diagram Block — write and render flowcharts, sequence diagrams, and more as text
- Callout Block — highlight notes, warnings, tips, and other short messages inline