More shortcode docs update

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)
 

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)",

Cargo.toml

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

components/rendering/src/shortcode.rs

@@ -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()),
-                        _ => unreachable!("Got something weird in an ignored shortcode"),
+                        _ => unreachable!("Got something weird in an ignored shortcode: {:?}", p2),
                     }
                 }
             },

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).