Indent shortcodes as much as their starting line

Author: ISSOtm

Diff for: components/markdown/src/shortcode/mod.rs

@@ -75,6 +75,7 @@ mod tests {
                         args: to_value(&HashMap::<u8, u8>::new()).unwrap(),
                         span: 0..SHORTCODE_PLACEHOLDER.len(),
                         body: None,
+                        indent: String::new(),
                         nth: 1,
                         inner: Vec::new(),
                         tera_name: "shortcodes/a.md".to_owned(),
@@ -84,6 +85,7 @@ mod tests {
                         args: to_value(&HashMap::<u8, u8>::new()).unwrap(),
                         span: SHORTCODE_PLACEHOLDER.len()..(2 * SHORTCODE_PLACEHOLDER.len()),
                         body: None,
+                        indent: String::new(),
                         nth: 2,
                         inner: Vec::new(),
                         tera_name: "shortcodes/a.md".to_owned(),
@@ -105,6 +107,7 @@ mod tests {
                     args: to_value(&HashMap::<u8, u8>::new()).unwrap(),
                     span: 9..(9 + SHORTCODE_PLACEHOLDER.len()),
                     body: Some("Content of the body".to_owned()),
+                    indent: String::new(),
                     nth: 1,
                     inner: Vec::new(),
                     tera_name: "shortcodes/bodied.md".to_owned(),
@@ -125,12 +128,14 @@ mod tests {
                     args: to_value(&HashMap::<u8, u8>::new()).unwrap(),
                     span: 9..(9 + SHORTCODE_PLACEHOLDER.len()),
                     body: Some(format!("Content of {SHORTCODE_PLACEHOLDER}")),
+                    indent: String::new(),
                     nth: 1,
                     inner: vec![Shortcode {
                         name: "bodied".to_string(),
                         args: to_value(&HashMap::<u8, u8>::new()).unwrap(),
                         span: 11..(11 + SHORTCODE_PLACEHOLDER.len()),
                         body: Some("the body".to_owned()),
+                        indent: String::new(),
                         nth: 1,
                         inner: Vec::new(),
                         tera_name: "shortcodes/bodied.md".to_owned(),

Diff for: components/markdown/src/shortcode/parser.rs

@@ -16,6 +16,7 @@ pub struct Shortcode {
     // In practice, span.len() is always equal to SHORTCODE_PLACEHOLDER.len()
     pub(crate) span: Range<usize>,
     pub(crate) body: Option<String>,
+    pub(crate) indent: String,
     pub(crate) nth: usize,
     pub(crate) inner: Vec<Shortcode>,
     // set later down the line, for quick access without needing the definitions
@@ -88,9 +89,20 @@ impl Shortcode {
         new_context.insert("nth", &self.nth);
         new_context.extend(context.clone());
 
-        let res = utils::templates::render_template(&tpl_name, tera, new_context, &None)
-            .with_context(|| format!("Failed to render {} shortcode", name))?
-            .replace("\r\n", "\n");
+        let rendered = utils::templates::render_template(&tpl_name, tera, new_context, &None)
+            .with_context(|| format!("Failed to render {} shortcode", name))?;
+        // Append the rendered text, but indenting each line after the first one as much as the line in which the shortcode was called.
+        let mut res = String::with_capacity(rendered.len());
+        let mut lines = rendered.split_terminator('\n');
+        if let Some(first_line) = lines.next() {
+            res.push_str(first_line.trim_end_matches('\r'));
+            res.push('\n');
+            for line in lines {
+                res.push_str(&self.indent);
+                res.push_str(line.trim_end_matches('\r'));
+                res.push('\n');
+            }
+        }
 
         Ok(res)
     }
@@ -246,17 +258,31 @@ pub fn parse_for_shortcodes(
 
     // We have at least a `page` pair
     for p in pairs.next().unwrap().into_inner() {
+        fn current_indent(text: &str) -> &str {
+            let current_line = match text.rsplit_once('\n') {
+                Some((_, line)) => line,
+                None => text,
+            };
+            // Stop at the first character that is not considered indentation by the CommonMark spec.
+            match current_line.split_once(|ch| ch != ' ' && ch != '\t') {
+                Some((whitespace, _)) => whitespace,
+                None => current_line,
+            }
+        }
+
         match p.as_rule() {
             Rule::text => output.push_str(p.as_span().as_str()),
             Rule::inline_shortcode => {
                 let start = output.len();
+                let indent = current_indent(&output).into();
                 let (name, args) = parse_shortcode_call(p);
                 let nth = invocation_counter.get(&name);
                 shortcodes.push(Shortcode {
                     name,
                     args,
                     span: start..(start + SHORTCODE_PLACEHOLDER.len()),
                     body: None,
+                    indent,
                     nth,
                     inner: Vec::new(),
                     tera_name: String::new(),
@@ -265,6 +291,7 @@ pub fn parse_for_shortcodes(
             }
             Rule::shortcode_with_body => {
                 let start = output.len();
+                let indent = current_indent(&output).into();
                 let mut inner = p.into_inner();
                 // 3 items in inner: call, body, end
                 // we don't care about the closing tag
@@ -279,6 +306,7 @@ pub fn parse_for_shortcodes(
                     args,
                     span: start..(start + SHORTCODE_PLACEHOLDER.len()),
                     body: Some(body),
+                    indent,
                     nth,
                     inner,
                     tera_name: String::new(),
@@ -422,6 +450,7 @@ mod tests {
             args: Value::Null,
             span: 10..20,
             body: None,
+            indent: String::new(),
             nth: 0,
             inner: Vec::new(),
             tera_name: String::new(),
@@ -442,6 +471,7 @@ mod tests {
             args: Value::Null,
             span: 42..65,
             body: None,
+            indent: String::new(),
             nth: 0,
             inner: Vec::new(),
             tera_name: String::new(),

Diff for: docs/content/documentation/content/shortcodes.md

@@ -167,6 +167,50 @@ If you want to have some content that looks like a shortcode but not have Zola t
 you will need to escape it by using `{%/*` and `*/%}` instead of `{%` and `%}`. You won't need to escape
 anything else until the closing tag.
 
+### Indentation
+
+If the shortcode expands to multiple lines, the lines after the first one will be indented as much as the first one:
+
+```jinja2
+- Second, heed this ancient wisdom:
+  {%/* quote(author=Vincent) */%}A quote{%/* end */%}
+```
+
+becomes...
+
+```md
+- Second, heed this ancient wisdom:
+  > A quote
+  > -- *Vincent*
+```
+
+But sometimes, the first line is not indented, and this breaks rendering:
+
+```jinja2
+- {%/* quote(author=Vincent) */%}A quote{%/* end */%}
+
+  ...are some wise words
+```
+
+becomes...
+
+```md
+- > A quote
+> -- *Vincent*
+
+  ...are some wise words
+```
+
+...which renders improperly (the second line of the quote onwards are not part of the list item).
+
+Since the first line of a list item can be empty, the fix is simply to add a new line:
+
+```jinja2
+-
+  {%/* quote(author=Vincent) */%}A quote{%/* end */%}
+  ...are some wise words
+```
+
 ## Shortcode context
 
 Every shortcode can access some variables, beyond what you explicitly passed as parameter. These variables are explained in the following subsections: