The story editor¶

The story editor at /lodeon/ is the authoring environment of LODEON, built into SHMARQL. LODEON's AI Assistant is left out, and the editor never calls a language model. You write a story in a visual editor, add Special Nodes from a menu, run their queries against the site's profiles, preview the story as the site will show it, and publish it.

The screen¶

The top bar has the project tools: the knowledge-graph selector, the data-story selector, New, Import, Export, Delete, the save status, Preview, Publish, Login, help and the day/night switch.
The metadata panel on the left holds the story's publication metadata and a list of its media assets.
The editor in the middle has a toolbar for text formatting and the Special Nodes menu.

The first time you open the editor it shows a Welcome Story, an ordinary project with a first SPARQL node for the default profile. Edit it, or start afresh with New.

Projects live in your browser¶

The editor is local-first: projects are stored in your browser (IndexedDB) and saved automatically as you type. The disk icon shows the save state; click it to save at once.

New creates an empty project. The data-story selector switches between the projects in this browser.
Export downloads the project as a .lodeon.zip package: the editable project (project.lodeon.json), the generated Markdown (story.md) and the media files (assets/…).
Import opens a .lodeon.zip. Packages from SHMARQL and from a full LODEON installation work in both directions. Assistant conversations in LODEON packages are dropped.
Delete removes the current project from this browser.

Export your work

Browser storage belongs to one browser on one computer, and clearing site data deletes it. Export regularly to keep a backup, or to continue on another machine.

Choosing the knowledge graph¶

The knowledge-graph selector lists the profiles of the site, by title. New Special Nodes use the selected profile, and each node remembers its own profile, so one story can mix several knowledge graphs. In the Markdown it appears as kg="<profile name>".

Writing text¶

The toolbar has undo/redo, zoom, the block type (paragraph, headings 1–6), bold, italic, underline, strikethrough, links, bullet and numbered lists, quotes, code blocks, horizontal rules, images by URL and tables (with add/remove row and column tools).

Special Blocks and rich-text formats

LODEON can be set up with extra Special Blocks (layout containers such as tiles or callouts) and custom block and inline formats. SHMARQL's editor has none configured, so the Special Blocks menu and the format menus don't appear. Everything else works as in LODEON.

Inserting Special Nodes¶

Put the cursor where the node should go and choose it from the Special Nodes menu:

Menu entry	What it does	Example
Media Asset	Upload an image, audio or video file.	media-asset
Embed Remote Content	Show a page from an allowed site in a frame.	embed
IIIF Object	Deep-zoom IIIF images.	iiif
Graph Explorer	An interactive network.	graph-explorer
Leaflet Map	A map.	leaflet-map
Music Notation	Scores in MEI or Plaine & Easie.	music-notation
SPARQL Query	A query and its results, with the optional Visual Query Builder.	sparql-query
Plotly Visualization	A chart.	plotly
RAWGraphs Visualization	A chart from RAWGraphs.	rawgraphs
Story Metadata	The story's metadata as a box in the text.	story-metadata

The Special Nodes reference describes every node and its settings.

The node header¶

Every Special Node has a header with:

a drag handle to move it, and move up / move down buttons;
collapse / expand, to fold a node away while you write;
copy, to duplicate it;
exclude from rendered output: the node stays in the project but is left out of the Markdown, Preview and Publish. It is useful for scratch queries. (The showcase package contains such a node.)
delete.

Results tables¶

SPARQL results in the editor (in SPARQL Query nodes, and in the query parts of map, IIIF, embed, graph and music nodes) can be paged, filtered, resized (10, 50, 100, … rows per page) and downloaded as CSV.

Metadata¶

The metadata panel holds what the site needs to publish and cite the story:

Field	Used for
Slug	The folder and address: `/story/<slug>/`. Letters, digits, `-` and `_` only.
Description, Keywords, Language, License	Front matter, HTML `<meta>` tags, Open Graph and schema.org JSON-LD.
Contributors	Name, role (author, editor, translator, …), affiliation and identifiers (for example an ORCID URL). Authors and editors become `schema:author` / `schema:editor` in the JSON-LD.
Persistent identifiers	DOIs, Handles, … under which the story is published.
Publish Story ZIP	Also publish the `.lodeon.zip` package next to the story, so readers can download and reuse it.

The published story card shows the address of the last publication. A Story Metadata node shows the same information inside the story.

Preview and Publish¶

Preview renders the story exactly as the site will, with the same pipeline, theme and runtime, in a preview panel. Previews are temporary (LODEON_PREVIEW_TTL, one hour by default).

Publish writes the story into the site:

DOCS_PATH/story/<slug>/index.md
DOCS_PATH/story/<slug>/assets/…
DOCS_PATH/story/<slug>/<slug>.lodeon.zip     (with "Publish Story ZIP")

The story then appears at /story/<slug>/ and in the navigation. Publishing again with the same slug replaces the earlier version in one step. Readers never see a half-written story.

Logging in¶

Publishing changes the website, so it needs a password. The site operator sets LODEON_EDITOR_TOKEN. Authors click Login in the top bar and enter that token. Preview and Publish then work for the rest of the browser session (8 hours by default, LODEON_EDITOR_SESSION_TTL).

`LODEON_EDITOR_TOKEN`	Editor	Preview	Publish
not set	everyone	everyone	nobody
set	everyone	after login	after login

Set LODEON_EDITOR_ENABLED=0 to switch the editor off completely.

Trying it with the examples¶

Every example story has its .lodeon.zip next to it. To explore a node type:

Download, for example, leaflet-map.lodeon.zip.
In the editor, choose Import and pick the file.
Change something: move a point, run the query, switch the chart type.
Choose Preview to see the result as the site would show it.

Importing an example doesn't change the published example. Only Publish does, and only with the same slug.