Add some basic docs for shortcodes

This commit is contained in:
Vincent Prouillet 2017-03-30 13:15:55 +09:00
parent d03974270d
commit 6a05e5d98d

View file

@ -149,6 +149,46 @@ built-in:
A gallery containing lots of themes at https://tmtheme-editor.herokuapp.com/#!/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:
```markdown
{{ youtube(id="my_youtube_id") }}
```
Shortcodes with a body are called like so:
```markdown
{% quote(author="Me", link="https://google.com") %}
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
- [vincent.is](https://vincent.is): https://gitlab.com/Keats/vincent.is