Skip to content

Commit

Permalink
Shortcodes: Mention argument parens are mandatory (#1752)
Browse files Browse the repository at this point in the history
  • Loading branch information
philpax authored Feb 7, 2022
1 parent a7abc84 commit 542daa7
Showing 1 changed file with 25 additions and 1 deletion.
26 changes: 25 additions & 1 deletion docs/content/documentation/content/shortcodes.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,8 @@ There are two kinds of shortcodes:
- ones that do not take a body, such as the YouTube example above
- ones that do, such as one that styles a quote

In both cases, the arguments must be named and they will all be passed to the template.
In both cases, the arguments must be named and they will all be passed to the template.
Parentheses are mandatory even if there are no arguments.

Lastly, a shortcode name (and thus the corresponding `.html` file) as well as the argument names
can only contain numbers, letters and underscores, or in Regex terms `[0-9A-Za-z_]`.
Expand Down Expand Up @@ -130,6 +131,29 @@ A quote
The body of the shortcode will be automatically passed down to the rendering context as the `body` variable and needs
to be on a new line.

### Shortcodes with no arguments
Note that for both cases that the parentheses for shortcodes are necessary.
A shortcode without the parentheses will render as plaintext and no warning will be emitted.

As an example, this is how an `aside` shortcode-with-body with no arguments would be defined in `aside.html`:
```jinja2
<aside>
{{ body }}
</aside>
```

We could use it in our Markdown file like so:

```md
Readers can refer to the aside for more information.

{%/* aside() */%}
An aside
{%/* end */%}
```

### Content similar to shortcodes

If you want to have some content that looks like a shortcode but not have Zola try to render it,
you will need to escape it by using `{%/*` and `*/%}` instead of `{%` and `%}`. You won't need to escape
anything else until the closing tag.
Expand Down

0 comments on commit 542daa7

Please sign in to comment.