From d334b1cf46121da36ae2b641fbf1726d65ed0fed Mon Sep 17 00:00:00 2001 From: Vincent Prouillet Date: Thu, 17 May 2018 19:04:42 +0200 Subject: [PATCH] More shortcode docs update --- CHANGELOG.md | 4 ++++ Cargo.lock | 2 +- Cargo.toml | 2 +- components/rendering/src/shortcode.rs | 12 +++++----- .../documentation/content/shortcodes.md | 24 ++++++++++++------- 5 files changed, 27 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 75864499..70d1e890 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ - Fix `serve` not working with the config flag - 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) diff --git a/Cargo.lock b/Cargo.lock index a22e66c7..e28a6aa9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -420,7 +420,7 @@ dependencies = [ [[package]] name = "gutenberg" -version = "0.3.4" +version = "0.4.0" dependencies = [ "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)", diff --git a/Cargo.toml b/Cargo.toml index 43b5269c..117d9768 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "gutenberg" -version = "0.3.4" +version = "0.4.0" authors = ["Vincent Prouillet "] license = "MIT" readme = "README.md" diff --git a/components/rendering/src/shortcode.rs b/components/rendering/src/shortcode.rs index 913a0d7c..6ccc12f8 100644 --- a/components/rendering/src/shortcode.rs +++ b/components/rendering/src/shortcode.rs @@ -153,14 +153,14 @@ pub fn render_shortcodes(content: &str, tera: &Tera, config: &Config) -> Result< for p2 in p.into_inner() { match p2.as_rule() { Rule::ignored_sc_body_start | Rule::ignored_sc_body_end => { - res.push_str( - &p2.into_span().as_str() - .replacen("{%/*", "{%", 1) - .replacen("*/%}", "%}", 1) - ); + res.push_str( + &p2.into_span().as_str() + .replacen("{%/*", "{%", 1) + .replacen("*/%}", "%}", 1) + ); }, 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), } } }, diff --git a/docs/content/documentation/content/shortcodes.md b/docs/content/documentation/content/shortcodes.md index 3b7d50c5..8b878a0b 100644 --- a/docs/content/documentation/content/shortcodes.md +++ b/docs/content/documentation/content/shortcodes.md @@ -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. -Any shortcodes in code blocks will be ignored. - 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_]`. 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` - float: a number with 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. ### 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. ```md @@ -68,9 +67,12 @@ Here is a YouTube video: {{/* 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 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 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 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: ```md -{{/* streamable(id="2zt0") */}} +{{/* streamable(id="92ok4") */}} -{{/* streamable(id="2zt0", class="streamble") */}} +{{/* streamable(id="92ok4", class="streamble") */}} ``` Result example: -{{ streamable(id="2zt0") }} +{{ streamable(id="92ok4") }} ### Gist Embed a [Github gist](https://gist.github.com).