More shortcode docs update

This commit is contained in:
Vincent Prouillet 2018-05-17 19:04:42 +02:00
parent b120754862
commit d334b1cf46
5 changed files with 27 additions and 17 deletions

View file

@ -5,6 +5,10 @@
- Fix `serve` not working with the config flag - Fix `serve` not working with the config flag
- Websocket port on `live` will not get the first available port instead of a fixed one - Websocket port on `live` will not get the first available port instead of a fixed one
- Rewrite markdown rendering to fix all known issues with shortcodes
- Add array arguments to shortcodes and allow single-quote/backtick strings
- Co-located assets are now permalinks
- Words are now counted using unicode rather than whitespaces
## 0.3.4 (2018-06-22) ## 0.3.4 (2018-06-22)

2
Cargo.lock generated
View file

@ -420,7 +420,7 @@ dependencies = [
[[package]] [[package]]
name = "gutenberg" name = "gutenberg"
version = "0.3.4" version = "0.4.0"
dependencies = [ dependencies = [
"chrono 0.4.4 (registry+https://github.com/rust-lang/crates.io-index)", "chrono 0.4.4 (registry+https://github.com/rust-lang/crates.io-index)",
"clap 2.31.2 (registry+https://github.com/rust-lang/crates.io-index)", "clap 2.31.2 (registry+https://github.com/rust-lang/crates.io-index)",

View file

@ -1,6 +1,6 @@
[package] [package]
name = "gutenberg" name = "gutenberg"
version = "0.3.4" version = "0.4.0"
authors = ["Vincent Prouillet <prouillet.vincent@gmail.com>"] authors = ["Vincent Prouillet <prouillet.vincent@gmail.com>"]
license = "MIT" license = "MIT"
readme = "README.md" readme = "README.md"

View file

@ -160,7 +160,7 @@ pub fn render_shortcodes(content: &str, tera: &Tera, config: &Config) -> Result<
); );
}, },
Rule::text_in_ignored_body_sc => res.push_str(p2.into_span().as_str()), Rule::text_in_ignored_body_sc => res.push_str(p2.into_span().as_str()),
_ => unreachable!("Got something weird in an ignored shortcode"), _ => unreachable!("Got something weird in an ignored shortcode: {:?}", p2),
} }
} }
}, },

View file

@ -41,24 +41,23 @@ There are two kinds of shortcodes:
In both cases, their arguments must be named and they will all be passed to the template. In both cases, their arguments must be named and they will all be passed to the template.
Any shortcodes in code blocks will be ignored.
Lastly, a shortcode name (and thus the corresponding `.html` file) as well as the arguments name Lastly, a shortcode name (and thus the corresponding `.html` file) as well as the arguments name
can only contain numbers, letters and underscores, or in Regex terms the following: `[0-9A-Za-z_]`. can only contain numbers, letters and underscores, or in Regex terms the following: `[0-9A-Za-z_]`.
While theoretically an argument name could be a number, it will not be possible to use it in the template in that case. While theoretically an argument name could be a number, it will not be possible to use it in the template in that case.
Argument values can be of 4 types: Argument values can be of 5 types:
- string: surrounded by double quotes `"..."` - string: surrounded by double quotes, single quotes or backticks
- bool: `true` or `false` - bool: `true` or `false`
- float: a number with a `.` in it - float: a number with a `.` in it
- integer: a number without a `.` in it - integer: a number without a `.` in it
- array: an array of any kind of values, except arrays
Malformed values will be silently ignored. Malformed values will be silently ignored.
### Shortcodes without body ### Shortcodes without body
On a new line, call the shortcode as if it was a Tera function in a variable block. All the examples below are valid Simply call the shortcode as if it was a Tera function in a variable block. All the examples below are valid
calls of the YouTube shortcode. calls of the YouTube shortcode.
```md ```md
@ -68,9 +67,12 @@ Here is a YouTube video:
{{/* youtube(id="dQw4w9WgXcQ", autoplay=true) */}} {{/* youtube(id="dQw4w9WgXcQ", autoplay=true) */}}
{{/* youtube(id="dQw4w9WgXcQ", autoplay=true, class="youtube") */}} An inline {{/* youtube(id="dQw4w9WgXcQ", autoplay=true, class="youtube") */}} shortcode
``` ```
Note that if you want to have some content that looks like a shortcode but not have Gutenberg try to render it,
you will need to escape it by using `{{/*` and `*/}}` instead of `{{` and `}}`.
### Shortcodes with body ### Shortcodes with body
For example, let's imagine we have the following shortcode `quote.html` template: For example, let's imagine we have the following shortcode `quote.html` template:
@ -94,6 +96,10 @@ A quote
The body of the shortcode will be automatically passed down to the rendering context as the `body` variable and needs The body of the shortcode will be automatically passed down to the rendering context as the `body` variable and needs
to be in a newline. to be in a newline.
If you want to have some content that looks like a shortcode but not have Gutenberg 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.
## Built-in shortcodes ## Built-in shortcodes
Gutenberg comes with a few built-in shortcodes. If you want to override a default shortcode template, Gutenberg comes with a few built-in shortcodes. If you want to override a default shortcode template,
@ -154,14 +160,14 @@ The arguments are:
Usage example: Usage example:
```md ```md
{{/* streamable(id="2zt0") */}} {{/* streamable(id="92ok4") */}}
{{/* streamable(id="2zt0", class="streamble") */}} {{/* streamable(id="92ok4", class="streamble") */}}
``` ```
Result example: Result example:
{{ streamable(id="2zt0") }} {{ streamable(id="92ok4") }}
### Gist ### Gist
Embed a [Github gist](https://gist.github.com). Embed a [Github gist](https://gist.github.com).