---
name: markdownto-guided-narration
description: Author spoken tours of Markdown documents or webpages with deterministic passage and image targets.
---
# Markdown To guided narration
Read `mdto spec guided-narration` or the adjacent `SPEC.md` before authoring.
Outside a checkout, read the [published spec](https://markdownto.ai/specs/guided-narration.md).
The spec and fixtures define conformance; the editorial advice here adapts to the user's brief.
## Write speech against the source
Set `markdownto: [email protected]` and `source` to a relative Markdown path or
HTTPS URL. Read or capture the source through an available tool before choosing targets.
The source reference itself never instructs the renderer or validator to fetch a website.
For a third-party webpage, supply a capture or imported source in the reader; ownership
or permission to modify the original website is not required for this separate manuscript.
Each paragraph is one spoken beat of 1–1200 characters, with exactly one target field.
Use `##` for chapter navigation; headings are not spoken. Write transitions in the speech.
Do not put lists, tables, HTML, blockquotes, or stage directions in the manuscript.
Do not invent timestamps, CSS selectors, block IDs, or automatic summarization instructions.
Prefer `[target-quote:: exact passage]` copied from the source. Matching normalizes
whitespace but remains case-sensitive. If the quote appears in multiple blocks, choose a
more distinctive quote or add `[target-prefix:: previous block ending]` and/or
`[target-suffix:: next block beginning]`. These refer to neighboring blocks, not context
inside the matched block. Use `[target:: #existing-id]` only for a known captured block ID.
Keep the field in the spoken paragraph; a blank line starts another beat.
To explain an image, target its captured caption or alt text, or its existing captured
block ID. Say what to look at and explain what it means. Describe only details the source
actually shows. The embedded reader supports bundled demo illustrations and embedded raster
images; a remote image URL is not automatically fetched. Inspect the rendered capture to
confirm that the intended picture is present, not merely its caption.
## Make the tour worth hearing
Choose an audience and a purpose from the brief. Explain relationships and consequences
rather than reading every visible sentence aloud. Keep each beat tied to one useful visual
stop. Give the listener enough context to understand a diagram without pretending a conceptual
illustration is historical evidence. Distinguish sourced facts from analogies and interpretation.
Use shorter paragraphs when a long explanation moves attention across several elements.
## Resolve before delivery
Validate the manuscript with `mdto validate tour.md`. Read `mdto guided-narration --help`
for the current inspect and resolve commands. Resolution takes an explicit JSON capture:
`{ "source": "./article.md", "blocks": [{ "id": "intro", "text": "Exact source passage" }] }`.
The capture's source string must match the manuscript exactly; IDs must be unique and nonempty.
Resolve every target against that capture and fix missing or ambiguous matches before playback.
The reader's Download capture for agents action exports its actual blocks for this purpose.
Render and inspect the tour, including any image stops. Confirm the actual speech, target
order, and chapter navigation. The runtime speaks authored paragraphs without rewriting them.
The hosted playground uses Hub-authenticated Gemini when available and computer voice otherwise;
validation and rendering do not generate audio. Do not claim cloud playback was verified from
conformance checks alone. For a local checkout, use `node site/tools/preview.mjs 4382` so
authenticated audio can reach the existing service through the fixed local relay.
Give this guide to your agent, or read it as an author. It covers workflow and editorial judgment; the specification defines conformance.
Read mdto spec guided-narration or the adjacent SPEC.md before authoring. Outside a checkout, read the published spec. The spec and fixtures define conformance; the editorial advice here adapts to the user's brief.
Write speech against the source
Set markdownto: [email protected] and source to a relative Markdown path or HTTPS URL. Read or capture the source through an available tool before choosing targets. The source reference itself never instructs the renderer or validator to fetch a website. For a third-party webpage, supply a capture or imported source in the reader; ownership or permission to modify the original website is not required for this separate manuscript.
Each paragraph is one spoken beat of 1–1200 characters, with exactly one target field. Use ## for chapter navigation; headings are not spoken. Write transitions in the speech. Do not put lists, tables, HTML, blockquotes, or stage directions in the manuscript. Do not invent timestamps, CSS selectors, block IDs, or automatic summarization instructions.
Prefer [target-quote:: exact passage] copied from the source. Matching normalizes whitespace but remains case-sensitive. If the quote appears in multiple blocks, choose a more distinctive quote or add [target-prefix:: previous block ending] and/or [target-suffix:: next block beginning]. These refer to neighboring blocks, not context inside the matched block. Use [target:: #existing-id] only for a known captured block ID. Keep the field in the spoken paragraph; a blank line starts another beat.
To explain an image, target its captured caption or alt text, or its existing captured block ID. Say what to look at and explain what it means. Describe only details the source actually shows. The embedded reader supports bundled demo illustrations and embedded raster images; a remote image URL is not automatically fetched. Inspect the rendered capture to confirm that the intended picture is present, not merely its caption.
Make the tour worth hearing
Choose an audience and a purpose from the brief. Explain relationships and consequences rather than reading every visible sentence aloud. Keep each beat tied to one useful visual stop. Give the listener enough context to understand a diagram without pretending a conceptual illustration is historical evidence. Distinguish sourced facts from analogies and interpretation. Use shorter paragraphs when a long explanation moves attention across several elements.
Resolve before delivery
Validate the manuscript with mdto validate tour.md. Read mdto guided-narration --help for the current inspect and resolve commands. Resolution takes an explicit JSON capture: { "source": "./article.md", "blocks": [{ "id": "intro", "text": "Exact source passage" }] }. The capture's source string must match the manuscript exactly; IDs must be unique and nonempty. Resolve every target against that capture and fix missing or ambiguous matches before playback. The reader's Download capture for agents action exports its actual blocks for this purpose.
Render and inspect the tour, including any image stops. Confirm the actual speech, target order, and chapter navigation. The runtime speaks authored paragraphs without rewriting them. The hosted playground uses Hub-authenticated Gemini when available and computer voice otherwise; validation and rendering do not generate audio. Do not claim cloud playback was verified from conformance checks alone. For a local checkout, use node site/tools/preview.mjs 4382 so authenticated audio can reach the existing service through the fixed local relay.