RenderShortcodes.md - hugo - [fork] hugo port for 9front
 (HTM) git clone https://git.drkhsh.at/hugo.git
 (DIR) Log
 (DIR) Files
 (DIR) Refs
 (DIR) Submodules
 (DIR) README
 (DIR) LICENSE
       ---
       RenderShortcodes.md (2627B)
       ---
            1 ---
            2 title: RenderShortcodes
            3 description: Renders all shortcodes in the content of the given page, preserving the surrounding markup.
            4 categories: []
            5 keywords: []
            6 params:
            7   functions_and_methods:
            8     returnType: template.HTML
            9     signatures: [PAGE.RenderShortcodes]
           10 ---
           11 
           12 Use this method in shortcode templates to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents.
           13 
           14 For example:
           15 
           16 ```go-html-template {file="layouts/_shortcodes/include.html" copy=true}
           17 {{ with .Get 0 }}
           18   {{ with $.Page.GetPage . }}
           19     {{- .RenderShortcodes }}
           20   {{ else }}
           21     {{ errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
           22   {{ end }}
           23 {{ else }}
           24   {{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }}
           25 {{ end }}
           26 ```
           27 
           28 Then call the shortcode in your Markdown:
           29 
           30 ```text {file="content/about.md"}
           31 {{%/* include "/snippets/services" */%}}
           32 {{%/* include "/snippets/values" */%}}
           33 {{%/* include "/snippets/leadership" */%}}
           34 ```
           35 
           36 Each of the included Markdown files can contain calls to other shortcodes.
           37 
           38 ## Shortcode notation
           39 
           40 In the example above it's important to understand the difference between the two delimiters used when calling a shortcode:
           41 
           42 - `{{</* myshortcode */>}}` tells Hugo that the rendered shortcode does not need further processing. For example, the shortcode content is HTML.
           43 - `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is Markdown.
           44 
           45 Use the latter for the "include" shortcode described above.
           46 
           47 ## Further explanation
           48 
           49 To understand what is returned by the `RenderShortcodes` method, consider this content file
           50 
           51 ```text {file="content/about.md"}
           52 +++
           53 title = 'About'
           54 date = 2023-10-07T12:28:33-07:00
           55 +++
           56 
           57 {{</* ref "privacy" */>}}
           58 
           59 An *emphasized* word.
           60 ```
           61 
           62 With this template code:
           63 
           64 ```go-html-template
           65 {{ $p := site.GetPage "/about" }}
           66 {{ $p.RenderShortcodes }}
           67 ```
           68 
           69 Hugo renders this:;
           70 
           71 ```html
           72 https://example.org/privacy/
           73 
           74 An *emphasized* word.
           75 ```
           76 
           77 Note that the shortcode within the content file was rendered, but the surrounding Markdown was preserved.
           78 
           79 ## Limitations
           80 
           81 The primary use case for `.RenderShortcodes` is inclusion of Markdown content. If you try to use `.RenderShortcodes` inside `HTML` blocks when inside Markdown, you will get a warning similar to this:
           82 
           83 ```text
           84 WARN .RenderShortcodes detected inside HTML block in "/content/mypost.md"; this may not be what you intended ...
           85 ```
           86 
           87 The above warning can be turned off is this is what you really want.