CustomComponents

Contentsgarten allows adding custom components on the page by leveraging the directive syntax, a proposed Markdown extension.

They can be used to render elements other than those defined by Markdown.

Examples

On Creatorsgarten wiki:

  • :::Draft — Mark a piece of text as a draft
  • ::Message — Displays a message balloon, facilitates using a wiki as a discussion medium.
  • :Icon — Displays an icon.

Basic Syntax

The syntax look like this:

  • Inline components are considered an inline element. It will be wrapped in a paragraph if used on its own.

    :ComponentName[label]{key=value}

  • Block components are considered a block element without children.

    ::ComponentName[label]{key=value}

  • Container components can contain children.

    :::ComponentName[label]{key=value}
children contents
:::

Rules:

  • ComponentName must start with an uppercase to be recognized.
  • [label] and {key=value} parts are optional.

How it works

  1. When Markdown is being rendered into HTML by @contentsgarten/markdown, it is converted into a custom element syntax. (This is done by Contentsgarten backend.)

    For example this:

    :::Greeting
World
:::

    …gets turned into this:

    <markdown-directive type="containerDirective" name="Greeting">World</markdown-directive>

  2. In the frontend, when the HTML is being rendered into React elements with @contentsgarten/html, a list of customComponents can be passed to <Html />.

    <Html html={src} customComponents={ { containerDirective: { Greeting } } } />

    …where Greeting is defined like this:

    function Greeting({ children }) {
  return <span>Ahoy {children}</span>
}

    …it is rendered into HTML like this:

    <span>Ahoy World</span>