Data stories¶

A data story is a page that tells something with data: text, mixed with live SPARQL results, charts, maps, network graphs, zoomable museum images, embedded pages, media files and music notation. SHMARQL renders data stories written with LODEON, an open-source authoring environment for Linked Data storytelling, and it includes LODEON's visual editor.

Part	What it is
Text	Headings, paragraphs, lists, quotes, tables, links, images by URL, code blocks.
Special Nodes	Functional blocks: a query, a chart, a map, … Each one is a fenced block in the Markdown.
Metadata	Title, description, authors, licence, … in the front matter, and from there in the page head (HTML meta, Open Graph, schema.org JSON-LD).
Assets	Local images, audio and video in an `assets/` folder next to the story.

The Special Nodes¶

Special Node	Shows	Data from
SPARQL Query	A results table, run when the page is read	A profile
Plotly Visualization	A bar, line, pie, scatter, map… chart	SPARQL, CSV/TSV pasted or from a URL
RAWGraphs Visualization	A chart designed in RAWGraphs, as SVG	A `.rawgraphs` project
Leaflet Map	Points, lines and areas on a map	SPARQL, points entered by hand, GeoJSON
Graph Explorer	An interactive network around resources	IRIs or SPARQL, expanded live
IIIF Object	Deep-zoom images from IIIF manifests	URLs or SPARQL
Embed Remote Content	Pages from allowed sites, in a frame	URLs or SPARQL
Media Asset	A local image, audio or video file	An upload
Music Notation	Engraved, playable scores (Verovio)	MEI or PAE text, a file, or SPARQL
Story Metadata	The story's metadata, visibly in the page	The project metadata

Every one of them has a working example in Example stories.

Three ways to make a data story¶

In the story editor at /lodeon/, the easy way: write, insert Special Nodes from a menu, preview, and publish to the site with one click. See The story editor.
In LODEON itself, if you run a full LODEON installation: export the story and copy its index.md and assets/ into the docs folder. The formats are the same, and .lodeon.zip packages move between LODEON and SHMARQL in both directions.
By hand, in any text editor: a data story is a Markdown file with fenced blocks. See The Markdown format.

Where stories live¶

A story is a folder in the documentation (DOCS_PATH):

story/
  showcase/
    index.md                  ← the story
    assets/images/night-watch.jpg
    showcase.lodeon.zip       ← optional: the editable project

The story editor publishes to DOCS_PATH/story/<slug>/ (the folder name is set by LODEON_STORY_DIR). The story appears at /story/<slug>/ and in the navigation. You can also put stories anywhere else in the docs folder.

How a story is shown¶

When SHMARQL renders a page, it treats it as a data story if the front matter has a lodeon: section or the page contains shmarql or lodeon-… fenced blocks. Then:

SPARQL Query, Plotly, RAWGraphs and IIIF blocks become placeholders that the LODEON browser script fills in. It runs the queries, draws the charts and opens the viewers.
Leaflet, Graph Explorer, Embed and Music Notation blocks are checked and turned into HTML on the server (with LODEON's own code), then made interactive in the browser.
Queries from the reader's browser go through SHMARQL's read-only API (/api/sparql/<profile name>), never directly to the triplestore.
A block that can't be shown (invalid JSON, a site that isn't allowed, an unknown map background) is replaced by a short error message. The rest of the page still works.

Queries run each time the page is read, so results are always current. That also means a story depends on its endpoints being up. Charts and maps keep the data they were made with, so they show even when the endpoint is slow.