EmbedResolver.h header

using ew::app::ChartImageResolver = std::function<QString(ew::core::ContentId chartId)>

Resolves a chart's content id to the <img> src to show it by – e.g. a PNG the caller has rendered and written into the export folder – or an empty string to fall back to the chart's data table. The desktop website export supplies this (rendering each embedded chart to a PNG via Qt Charts) so a published page shows the drawn chart; a headless or plain render passes none and gets the table. Kept as a callback so the GUI-free engine needs no Qt Charts dependency.

QString ew::app::embedMarker(const QString &target, const QString &section=QString())

Builds the canonical block-embed marker text – ![[target]], or ![[target#section]] when section is non-empty – escaping any #, ], or % inside a component so a target or section that itself contains one of those structural characters (e.g. an entity titled "Suspect #3" or a document "C# Notes") survives a round-trip through findEmbedMarkers unchanged. The # that separates target from section, and the ]] that terminates the marker, are the grammar's own delimiters; without escaping, a #/] in the target would be misparsed as a section boundary or an early terminator (silently corrupting the embed). This builder and findEmbedMarkers share the escape scheme, so they are exact inverses.

QString ew::app::embedTitle(const ew::core::ContentObject *object)

The title/name an embed marker matches object by: a document's title, an entity's name, or a spreadsheet's, map's, or chart's title. Empty for a null object or a non-embeddable type. Lets a client list the objects that can be embedded.

QString ew::app::expandEmbeds(const ew::core::Project &project, const QString &body)

Returns body with every embed marker replaced by its rendered HTML (renderEmbedHtml), leaving all other text untouched. This is the "live and export-aware" expansion used both to display embeds and to publish them.

QString ew::app::expandEmbeds(const ew::core::Project &project, const MountedLibraries &libraries, const QString &body)

Like expandEmbeds(), but resolves every marker across project and every library mounted into it via libraries, so embedded shared-library objects expand too.

QString ew::app::expandEmbedsToMarkdown(const ew::core::Project &project, const MountedLibraries *libraries, const QString &body)

Returns body with every block-embed marker replaced by a Markdown rendering of the embedded object, resolved across project and (when non-null) libraries: an entity as a name / category / summary snippet, a document as its title, synopsis, and body (or the named section), a spreadsheet or chart as a bounded GFM pipe table, a map as its region list, and an unresolved target as an italic note. Unlike expandEmbeds – which renders self-contained HTML cards – the output is Markdown, so a Markdown-consuming book export (Markdown, HTML, DOCX, EPUB, PDF, standard-manuscript RTF) shows the transcluded content inline instead of a literal ![[…]] marker. An embedded document's own body is normalized to Markdown the same way compileManuscript normalizes a host body (documentBodyMarkdown, driven by the document's BodyFormat tag). The website generator uses renderEmbeddedBodyHtml() instead (rich HTML cards + drawn chart images), so it does not call this. A body with no markers is returned unchanged.

std::vector< EmbedMarker > ew::app::findEmbedMarkers(const QString &body)

Finds every block-embed marker – ![[target]] or ![[target#section]] – in body, in order of appearance. A #, ], or % inside a target or section is understood in its escaped form (see embedMarker) so a marker built by embedMarker reparses to the exact target/section.

QString ew::app::renderEmbedHtml(const ew::core::Project &project, const EmbedMarker &marker)

Renders marker against project as a self-contained, read-only HTML block: an entity card (name/category/summary), a document (title, synopsis, and its body or the named section), a spreadsheet (a bounded HTML table), a map (title and region list), or a chart (title and a bounded data table – the desktop editor and website export overlay the drawn chart image). Returns a styled "unresolved embed" note when the target cannot be found. The HTML is shared by the editor's live view and by export, so an embed looks the same everywhere.

QString ew::app::renderEmbedHtml(const ew::core::Project &project, const MountedLibraries &libraries, const EmbedMarker &marker)

Like renderEmbedHtml(), but resolves marker across project and every library mounted into it via libraries, so a marker naming a shared-library object renders that object (an entity card uses the object's owning-repo schema, as the spanning preview does).

QString ew::app::renderEmbeddedBodyHtml(const ew::core::Project &project, const MountedLibraries &libraries, const QString &body)

Renders a Markdown document body to HTML with its ![[...]] block embeds expanded in place: the Markdown between markers is rendered by markdownToHtml and each marker by renderEmbedHtml (resolving across project and libraries), so an exported/published page shows transcluded content inline exactly as the editor's live view does. A body with no markers renders identically to markdownToHtml(body). This is the body renderer the website generator uses so embeds are live in the published site.

QString ew::app::renderEmbeddedBodyHtml(const ew::core::Project &project, const MountedLibraries &libraries, const QString &body, const ChartImageResolver &chartImage)

Like renderEmbeddedBodyHtml(project, libraries, body), but a chart embed is rendered as an <img> whose src comes from chartImage(chartId) when that returns a non-empty string (else the chart's data table). Every other embed and all Markdown render identically. Lets the desktop website export publish live chart images while the engine stays rendering-agnostic.

ew::core::ContentId ew::app::resolveEmbedTarget(const ew::core::Project &project, const QString &target)

Resolves an embed target (a title or name) to the id of the document, entity, spreadsheet, map, or chart it names, matched case-insensitively against object titles in project order. Returns a null id if nothing matches.

ew::core::ContentId ew::app::resolveEmbedTarget(const ew::core::Project &project, const MountedLibraries &libraries, const QString &target)

Like resolveEmbedTarget(), but matches across project and every library mounted into it via libraries, so an embed can name an object in a shared library (cross-library embeds resolve by global id). The project is searched first, then each library in mount order.

QString ew::app::stripHiddenEmbeds(const ew::core::Project &project, const QString &body, const QString &audience)

Returns body with the block-embed markers whose target is hidden from audience removed – a secret/GM-only callout (an audience-scoped embedded note, ContentObject::isVisibleTo) leaves no trace, not even its ![[…]] marker, in a restricted export (DESIGN 4.13). Unlike expandEmbeds it does NOT render the surviving embeds, so a Markdown/DOCX/EPUB compile keeps its live markers; the visible embeds are expanded later by the format's own renderer. An empty audience returns body unchanged (the author's full manuscript). Resolution is project-scoped.