Callouts, examples and the version placeholder
v0.0.1
An author places three kinds of component inside the text of a page or a note: a callout, a live example, and the cards of the pages under a page. A fourth item is not a component. The version placeholder is a word that the page fills in with the version a reader is reading. This reference lists their attributes, behavior and rules. For how to place them, see Write pages and notes.
How a component is placed
In the content editor, click Components, choose the component, and set its attributes in the drawer. The editor stores the component as a marker in a paragraph of its own: the word component, the component's name and attributes between double square brackets, the content that follows, and a closing marker with a slash. A component with no content is written as one self-closing marker.
The CMS draws a marker only where it is text. A marker inside a tag, inside <pre> or inside <code> is left as it is, so a page can show the syntax. A marker that does not parse, an opening marker nothing closes and a closing marker nothing opened are also left as text. Only a component the site may draw is drawn, and a marker may hold markers of its own, up to eight levels deep.
doc-callout
Draws a box in the page's text: a note, a tip, a warning. It draws only what it is handed. Its content is a line of text, or paragraphs and lists.
| Attribute | Type | Default | What it does |
|---|---|---|---|
tone | string | "note" | The kind of callout and the color of its box: note, info, tip, success, warning or danger. A tone the component does not know is drawn as a note. |
title | string | none | A line in bold above the content. Empty, none is drawn. |
The colors are neutral for note, blue for info, indigo for tip, green for success, amber for warning and red for danger. In a HEEx page, the callout is written like any component:
<.component component_name="doc-callout" site="Global" tone="tip" title="Before you start">
Run <code>mix deps.get</code> once the dependency is in <code>mix.exs</code>.
</.component>doc-example
Draws a live example inside the page. Its content is the markers of the components the example is made of. The content is drawn on the page itself, so the components' own hooks, events and popups work there, in the page's own colors. This is the example below, a tip callout inside an example:
A tip callout
Above the example, a toolbar turns it left to right or right to left, and opens its preview. The Preview button opens a dialog with the example drawn alone and live, in a frame, with the site's stylesheet and scripts. The dialog's toolbar switches Light and Dark, the width, Desktop at 1280 pixels, Tablet at 768 or Mobile at 375, and the direction. Close, Esc and a click on the backdrop close it. An example taller than collapse_height pixels is cut with a button that shows all of it.
| Attribute | Type | Default | What it does |
|---|---|---|---|
id | string | none | The id the toolbar's hook is mounted under. A page's text gives an example one from its place in the text. Drawn without one, the example has no toolbar and no preview. |
title | string | none | A line over the example saying what it shows. It is also the preview's name for a screen reader. |
theme | string | "dark" | The colors the preview is first drawn in: light or dark. The example on the page keeps the page's colors. |
device | string | "desktop" | The width the preview is first drawn at: desktop, tablet or mobile. |
dir | string | "ltr" | The direction the example is first drawn in, on the page and in the preview: ltr or rtl. |
collapse_height | integer | 320 | An example taller than this many pixels is cut at this height. Allowed: 0 (never cut), 240, 320, 400, 480, 640. |
source | string | none | Where the example is written: section/<id>/<n> or note/<id>/<n>, counted from 0. doc-section sets it. An example with none has no preview. |
The words of the example are attributes too, with these defaults.
| Attribute | Default | Names |
|---|---|---|
frame_label | "Example" | The preview frame, for a screen reader, when the example has no title. |
toolbar_label | "Example options" | The toolbar over the example. |
light_text, dark_text | "Light", "Dark" | The theme buttons. |
desktop_text, tablet_text, mobile_text | "Desktop", "Tablet", "Mobile" | The width buttons. |
ltr_text, rtl_text | "LTR", "RTL" | The direction buttons. |
preview_text | "Preview" | The button that opens the preview, and the preview's name when the example has no title. |
close_text | "Close" | The button that closes the preview. |
expand_text | "Show the whole example" | The button under a cut example. |
collapse_text | "Show less" | That button once the whole example is shown. |
The preview page
The preview frame shows /_preview/doc-example/<kind>/<id>/<index>. The kind is section or note, the id is a page's or a note's id, and the index is the example's place among the examples of that text, counted from 0 in the order written, including those inside other markers and none inside code. Anything else answers the site's 404.
The page reads the page or note as the visitor, so a locked page, a page waiting for review or a page of a draft version is not found. It is never indexed: the response carries x-robots-tag: noindex, nofollow, and the site's robots.txt disallows /_preview/. It is served with a Content-Security-Policy of its own that only the site itself may frame.
The version placeholder
Write {{doc.version}}, with or without spaces inside the braces, anywhere in a page's text or in a note, and the page draws the number of the version the reader is reading. On the page of 0.0.2 it reads 0.0.2, and on the same page of 0.0.1 it reads 0.0.1. A page stores the placeholder as written, so a version cloned from another draws its own number with nothing changed.
- It is filled in the text, in code blocks, and in the attributes of a component, so an install line such as
{:my_lib, "~> {{doc.version}}"}and a link to a release follow the version picked. - It is also filled in the headings listed by
doc-toc, in the summary of adoc-section-cardscard, and in the text of an example's preview. - In a highlighted code block it is filled where the highlighter left it in one token, inside a string or a comment.
- To show the placeholder itself, put a backslash before it. The backslash is not drawn.
doc-section-cards
Placed in a page's text or a note, doc-section-cards draws the pages filed under that page as cards. Its attributes are in Document list and card blocks.