# `MishkaDocumentWeb.Live.ExamplePreview`
[🔗](https://github.com/mishka-group/mishka_document/blob/v0.0.1/lib/mishka_document_web/live/example_preview.ex#L5)

One `doc-example` of a page of a document, or of one of its notes, drawn alone and live: the page
the kit's `doc-example` opens in its Preview dialog's frame, at
`/_preview/doc-example/<kind>/<id>/<n>` (`MishkaDocumentWeb.ExamplePreviewController`).

`kind` is `section` or `note`, `id` the page's or the note's id and `n` the example's place among
the `doc-example` markers of its text, counted from 0 in the order they are written — those inside
other markers too, and none inside `<pre>` or `<code>` — the rule `sources/2` writes and the kit's
`doc-section` writes with it (its `example_sources/2`), so the example a reader presses Preview on
is the one drawn here.

## What is read

What `doc-section` reads to draw the same text, with the same rules: the page through
`:public_list` as the visitor, so a page locked to permissions the visitor does not hold, or one
waiting for review, is not found; its version through `:public_list`, so a draft version's page
is not either; and its document through `:public_list`, so an archived one's is not. A note is
read through its own `:public_list` as the visitor, and then its page as above. All of it on the
site the address is asked on. Anything not found, and an example no marker of the text is at, is
the 404 every missing page is.

## What is drawn

The text is scrubbed as `doc-section` scrubs it, its `{{doc.version}}` is the number of the
page's version (`with_version/2`), and the example's own content — what its marker
holds — is drawn with `rich_content/1`, for the site the address is asked on and the visitor, as
the page draws it: its components, their hooks and their events are those of the page. The
document around it is the CMS's root layout for a database page: the site's compiled stylesheet
and scripts, a `noindex, nofollow` robots tag, and the language of the page the example is
written in. The theme and the direction the dialog shows it in are the dialog's to set on this
page's `<html>`, which a render here never touches.

An event no component of the example answers is ignored.

# `example`

```elixir
@spec example(String.t(), String.t()) :: map() | nil
```

The `doc-example` marker of `html` whose `source` is `wanted`, read from `html` with its sources
written (`sources/2`) — `%{name: "doc-example", attrs: attrs, inner: inner, index: n}`, as
`MishkaCmsCore.Runtime.ContentComponents.parse/1` reads a marker — or `nil`.

# `sources`

```elixir
@spec sources(String.t(), String.t()) :: String.t()
```

`html` with every `doc-example` marker in its text handed `source="<source>/<n>"` right after its
name, `n` counting them from 0 in the order they are written, those inside other markers too. A
marker inside `<pre>` or `<code>` is a page showing the syntax, and is left as it was written.
Text that names no `doc-example` is handed back as it is.

    sources(~s(<p>[[component doc-example title="A"]]x[[/component]]</p>), "section/…")
    #=> ~s(<p>[[component doc-example source="section/…/0" title="A"]]x[[/component]]</p>)

# `with_version`

```elixir
@spec with_version(String.t(), String.t() | nil) :: String.t()
```

`html` with every `{{doc.version}}` in it — `{{ doc.version }}` too, in code blocks and in a
marker's attributes as well — replaced by `number`, HTML-escaped; `\{{doc.version}}` is written
as `{{doc.version}}`. The kit's `doc-section`, `doc-toc` and `doc-section-cards` draw a page's
text by the same rule (their `with_version/2`). With no number, `html` is handed back as it is.

    with_version(~s(<code>{:lib, "~&gt; {{doc.version}}"}</code>), "1.2.0")
    #=> ~s(<code>{:lib, "~&gt; 1.2.0"}</code>)

---

*Consult [api-reference.md](api-reference.md) for complete listing*