Browse Source

Add some basic docs for shortcodes

Vincent Prouillet 4 years ago
1 changed files with 40 additions and 0 deletions
  1. +40

+ 40
- 0 View File

@@ -149,6 +149,46 @@ built-in:
A gallery containing lots of themes at!/editor/theme/Agola%20Dark.
More themes can be easily added to gutenberg, just make a PR with the wanted theme.

### Shortcodes
Gutenberg uses markdown for content but sometimes you want to insert some HTML, for example for a YouTube video.
Rather than copy/pasting the HTML around, Gutenberg supports shortcodes, allowing you to define templates using Tera and call those templates inside markdown.

#### Using a shortcode
There are 2 kinds of shortcodes: simple ones and those that take some content as body. All shortcodes need to be preceded by a blank line or they
will be contained in a paragraph.

Simple shortcodes are called the following way:

{{ youtube(id="my_youtube_id") }}

Shortcodes with a body are called like so:

{% quote(author="Me", link="") %}
My quote
{% end %}

The shortcodes names are taken from the files they are defined in, for example a shortcode with the name youtube will try to render
the template at `templates/shortcodes/youtube.html`.

#### Built-in shortcodes
Gutenberg comes with a few built-in shortcodes:

- YouTube: embeds a YouTube player for the given YouTube `id`. Also takes an optional `autoplay` argument that can be set to `true`
if wanted
- Vimeo: embeds a Vimeo player for the given Vimeo `id`
- Gist: embeds a Github gist from the `url` given. Also takes an optional `file` argument if you only want to show one of the files.

#### Defining a shortcode
All shortcodes need to be in the `templates/shortcodes` folder and their files to end with `.html`.
Shortcodes templates are simple Tera templates, with all the args being directly accessible in the template.

In case of shortcodes with a body, the body will be passed as the `body` variable.

## Example sites

- [](