# `MishkaDocument.Kit` [πŸ”—](https://github.com/mishka-group/mishka_document/blob/v0.0.1/lib/mishka_document/kit.ex#L5) Where this extension's UI kit bundle is, and how to install it. ## What is in the bundle, and why it is a bundle `priv/cms_ui_kits/mishka_document.json` carries eleven components of two kinds. Each is complete on its own: its markup, its declarations, and its own code, including the Ash reads it runs. Nothing about them lives in Elixir. ### The six blocks, which are live components `doc-workspace-list`, `doc-section`, `doc-sidebar`, `doc-toc`, `doc-switcher` and `doc-section-cards`. Each is a `Phoenix.LiveComponent` that runs its own reads, so an author can put any of them on any page and each holds what it read. The first five resolve the document from the URL; `doc-section-cards` from the page it is drawn in. ### The five pieces, which are function components `doc-workspace-card`, `doc-pager`, `doc-notice`, `doc-callout` and `doc-example`. These hold nothing and read nothing: they draw what they are handed. The notice is drawn by five of the six blocks β€” it is every skeleton but the list's own, every empty line and every failed read in this kit, bar the switcher's, which draws a small skeleton and error of its own to fit the bar it sits in β€” and the card is what `doc-workspace-list` draws a document with unless the author names a card of their own in its `card` attribute. The callout and the example are placed by an author inside a page's text, with the content editor β€” `[[component doc-callout tone="tip"]]…[[/component]]` β€” and drawn by `doc-section`'s `rich_content`, which names them for the site's stylesheet. ### The cards `[[component doc-section-cards /]]` in a page's text, or in one of its notes, draws the pages filed under that page as cards, two a row from the `sm` breakpoint and one under it: each its title, the badges a plugin puts on it, its summary β€” the description its own SEO gives it, else the start of its text β€” and a link to its address. `doc-section` hands the marker the page it is drawn in (`placed_in`) and the `doc_base`, `lang_param` and `version_param` it links with, after the scrub and never inside `
` or ``. `parent` names another page of the same version β€” by
its address, or by a slug only one page has, which is how a group with no page of its own is
named. The pages are the version's approved ones the visitor may read, read through
`public_list_at_workspace_version` as `doc-sidebar` reads them, under the parent the contents draw
each one under and in their order; a group with no page of its own gives up its pages in its
place. `doc-notice` draws its skeleton, its error and its empty line (`empty_text`).

Its badges are asked on `document:page:extras`, once a card, with the page as `doc-section` tells
it and `card: true`, and only the header's `:badges` are drawn. A plugin answering an ask with
`card: true` answers from what it already holds and fetches nothing; `show_badges=false` asks
nothing. Every element says what it is in its `data-role`: `doc-cards`, `doc-cards-heading`,
`doc-cards-items`, `doc-cards-item`, `doc-cards-link`, `doc-cards-title`, `doc-cards-badges`,
`doc-cards-badge` (`data-tone`), `doc-cards-description`, `doc-cards-empty`, `doc-cards-loading`
and `doc-cards-error`.

### The design they are drawn in

Every block is drawn in the starter theme's tokens β€” `text-fg dark:text-fg-dark`, `border-edge
dark:border-edge-dark`, `bg-surface dark:bg-surface-dark` and the rest β€” and in the three
typefaces it names, so the site's dark mode turns the whole documentation. A colour the theme has
no token for is written as a value with its `dark:` twin beside it. A site that was installed with
no starter content has no such theme, and draws these blocks in the browser's colours until it
has one.

  * `doc-workspace-list` draws a document as a card β€” its tile, how many pages and which version,
    its name, its summary, the languages it is published in and the way in β€” or, as one line of a
    list, as a row. `show_search` draws a search box over the list that narrows it to the documents
    whose name or summary carries the words, read from `search_param` of the page's own query
    string (`q`) and written back there, so a search has an address of its own; `split_featured`
    draws the documents flagged Featured as cards and every other one as a row under
    `others_heading`, the featured ones first. A document only some readers may open carries
    `locked_text`, and one that asks search engines to leave it out `unlisted_text`. Its tile is
    the first letter of its name β€” without a leading `Mishka ` β€” on one of six tints picked from
    the document (`doc-workspace-card`).
  * `doc-switcher` draws the version being read in a menu of the document's versions, each
    leading to the same page in it, and a line saying so, with the way to the latest, when it is
    an older one. It is drawn by the bar under the site's header
    (`MishkaDocument.Plugins.PageFrame`), at the end of the trail the bar draws itself, and has no
    trail and no languages of its own: the header's language switcher lists the languages the
    page is in. The bar hands it the visitor as `current_user` and the page's rows as
    `page_source`, so it reads each version's pages as the visitor: a version whose page this
    reader may not open leads to the document's front page.
  * `doc-section` draws a document's overview β€” its tile, its version and how many pages, its name
    and summary, the first `start_count` pages as numbered cards with the start of their text, and
    every page under the heading it is filed under β€” and a page with its trail, its title, its text
    and the pages either side. The first paragraph of a page's text is its lead. A callout
    (`doc-callout`) has six tones, each with its own mark.
  * `doc-toc` is the list of what is on the page; its `doc-toc-spy` hook marks the entry the reader
    has scrolled to.

### The version in a page's text

`{{doc.version}}` β€” or `{{ doc.version }}` β€” anywhere in a page's text or in one of its notes is
drawn as the number of the version the reader is reading: `0.0.2` on the page of 0.0.2, `0.0.1`
on the same page of 0.0.1. It is filled on the way out, after the scrub and HTML-escaped, in the
text, in its code blocks and in the attributes of a marker, so an install line, a link to a
release and a component's `href` each follow the version picked:

    
{:my_lib, "~> {{doc.version}}"}

    README

A page stores the placeholder as it was written, so a version cloned from another
(`MishkaDocument.Resources.Changes.CloneVersion`) draws its own number with nothing changed.
`\{{doc.version}}` is drawn as `{{doc.version}}`, for a page that shows the placeholder itself.
`doc-toc` lists a heading with its version filled the same way, a `doc-section-cards` card's
summary is the start of its page's text with it filled, and so is the text of an example's
preview (`MishkaDocumentWeb.Live.ExamplePreview`). In a highlighted code block it is filled
where the highlighter left it in one token β€” inside a string or a comment.

### The example

`[[component doc-example title="…"]]` around the markers of the components an example is made
of, then `[[/component]]`. Its `inner_block` is drawn on the page itself, in the example's
`doc-example-stage` and its `doc-example-body`, so the components' own hooks, events, popups and
breakpoints work there as anywhere on the page, in the page's own colours.

Its toolbar β€” `doc-example-toolbar`, named by `toolbar_label` β€” turns the example left to right or
right to left, and, for an example with a `source` (every one `doc-section` draws), its
`doc-example-open` button, saying `preview_text`, opens its preview: a ``
(`doc-example-preview`, opened as a modal) the hook builds the first time it opens, inside a
`doc-example-preview-holder` drawn with `phx-update="ignore"` and an id carrying a digest of the
words it is drawn with, so a LiveView patch never closes it and other words build a preview of
their own. The holder is drawn empty: it carries the preview's words and, in `data-src`, the page
its frame shows, and nothing else of the preview is drawn with the example, so an example costs a
page, and a LiveView patch, its own markup and the few elements around it. The frame
(`doc-example-frame`, named by `title` or `frame_label`) shows `/_preview/doc-example/`,
the page that draws that example alone and live with the site's stylesheet and scripts
(`MishkaDocumentWeb.Live.ExamplePreview`), only while the preview is open; it is
`sandbox="allow-scripts allow-same-origin allow-forms"`. The preview's own toolbar
(`doc-example-preview-toolbar`) switches its colours, its width β€” a desktop's 1280 pixels, a
tablet's 768 or a phone's 375, scaled down to fit a narrower preview β€” and the direction, and its
`doc-example-close` button, saying `close_text`, Escape and a press on the backdrop close it.

`theme` (light, dark; dark by default) and `device` (desktop, tablet, mobile; desktop) are what
the preview is first drawn with, and `dir` (ltr, rtl; ltr) is what the example is first drawn
with on the page and in the preview, carried on its root as `data-frame-theme`,
`data-frame-device` and `data-frame-dir`, and `dir` on the stage. Each choice is a
`doc-example-option` button with a `data-action` of theme, device or dir, a `data-value` and
`aria-pressed`. Every element, the preview's included, says what it is in its `data-role`, and
that is what the kit's stylesheet draws it by: no element of the example but its
`doc-example-body` carries a class, and a site's stylesheet restyles any of them by its
`data-role`. Drawn without an id the example has no toolbar and no preview.

An example taller than `collapse_height` pixels (320; 240, 400, 480 or 640, and 0 cuts none) is
cut at that height under a fade until the `doc-example-expand` button in the `doc-example-foot`
under it shows all of it, saying `expand_text` and then `collapse_text`. The root carries the
height as `data-collapse-height`; the hook measures the example's body and writes
`data-collapsible` onto the root β€” again whenever the body changes size β€” and the button writes
`data-expanded`. The cut clips only the example's height, so a popup still reaches past its sides.

An example holding a component that keeps state is drawn on the page like any other, and its
preview draws it live like any other.

They draw themselves in plain HTML and Tailwind and call no other kit. A site that installed this
extension and skipped Chelekom renders them; the components a documentation page is made of cannot
depend on a kit the installer only offers.

That is the same shape Chelekom ships in, and it is the point. A component that arrives as data
can be installed one at a time or in batches, can be edited in the admin like any other row, and
carries no dependency on a module a third-party importer would not have. An extension that kept
its components in compiled code would be asking the CMS to treat it specially.

### Who they read as

Every read is the public action's, with the visitor the page hands down as `current_user` as its
actor β€” `nil` for a guest β€” so a document or a page of one locked to permissions the visitor does
not hold is left out by the same rules the record's own page keeps
(`MishkaDocument.Resources.Preparations.OpenToActor`). The document a page sits in and its
versions are read as the system: a page whose own lock opens for the reader is drawn inside a
document whose lock does not.

## What the six are

`doc-workspace-list` lists the documents a site publishes. `doc-section` draws one page of one of
them β€” its body, its notes, the trail above it and the pages either side. `doc-sidebar` draws that
document's whole contents as a tree, `doc-toc` draws what is on the page being read, and
`doc-switcher` offers the document's versions, each leading to the same page in it.
`doc-section-cards` draws the pages filed under one page as cards.

A version may mark one page at its top as its front page: every block reads that page at the
document's own address, in place of the landing, links to it there, and files the pages under it
directly under that address (`MishkaDocument.Address`). A page marked as a group is only a heading
over the pages under it β€” in the contents and on the landing β€” with no page or address of its own:
nothing links to it, Previous and Next step over it, and its pages are addressed as if it were not
there. A group with a page of its own (`group_page`) is read at its own slug like any page β€” its
text, its notes, its trail β€” and its heading in the contents, its title on the landing and its
place in a trail link there; Previous and Next stop on it. The pages under it keep the address
that leaves its slug out.

Under a page's title `doc-section` says when it last changed and the version being read,
`Updated Oct 14, 2026 Β· v1.2.0` (`doc-section-updated`, the date in a `