NAME

App::Dapper::Components - Callouts, videos, galleries and more in Markdown.

DESCRIPTION

Components add things Markdown can't express, without template code. A component starts with three colons and its name. Most wrap Markdown and end with three colons on a line of their own:

::: warning "Before you start"
Back up your site first. **Really.**
:::

::: details "Show the full list"
- one
- two
:::

::: gallery
![The shop](shop.jpg)
![The team](team.jpg)
:::

Others are a single line:

::: youtube https://www.youtube.com/watch?v=dQw4w9WgXcQ "Our story"
::: vimeo 76979871 "A short film"
::: button /contact/ "Get in touch"
::: figure shop.jpg "The shop at night" "Open until 9pm on Fridays"
::: map "1 Main Street, Springfield"

The built-in components are:

note, tip, warning, important, callout

A box that stands out from the text, with an optional title. ::: callout tip is the same as ::: tip. HTML: <aside class="callout callout-tip">.

details

A section that opens when clicked, with the summary given.

The images inside, in a <div class="gallery">, for a grid.

youtube, vimeo

An embedded video, from its address or ID, with a title for screen readers. YouTube videos use youtube-nocookie.com.

button

A link styled as a button: <a class="button">.

figure

An image with alt text and an optional caption.

map

A map of an address, from Google Maps.

Words after the name are its arguments; put quotes around ones with spaces. To nest a component inside another, give the outer one more colons:

:::: note
::: details "More"
Hidden text
:::
::::

Components of your own

A theme or site can add components, or change how the built-in ones look, with templates in _layout/components. _layout/components/pricing.html is used for ::: pricing, with these variables:

args      The arguments: args.0 is the first, args.size how many,
          and args.list all of them, for FOR loops
content   The HTML of the Markdown inside it (empty for a single line)
page      The page
site      The site

Arguments written as name=value are also available by name, as args.name. A component is a single line unless a matching line of colons closes it.

names

Returns the names of the built-in components.

expand

Takes Markdown, a function that turns Markdown into HTML, and options: layout (the layout directory, for components of your own), vars (the page and site for their templates) and unknown (an array reference to collect the names of components that don't exist). Returns the Markdown with each component replaced by a placeholder line, and the HTML for each placeholder.

parse_args

Takes the text after a component's name and returns its arguments: words, or quoted text.

template

Takes the options given to "expand" and a component name, and returns the path of its template in _layout/components, if there is one.

render_template

Renders a component of your own with its template.

built_in

Takes a built-in component's name, arguments and inner HTML, and returns its HTML.

video_id

Takes youtube or vimeo and a video's address or ID, and returns its ID.