diff --git a/content/en/functions/RenderString.md b/content/en/functions/RenderString.md new file mode 100644 index 000000000..61f5d6417 --- /dev/null +++ b/content/en/functions/RenderString.md @@ -0,0 +1,37 @@ +--- +title: .RenderString +description: "Renders markup to HTML." +godocref: +date: 2019-12-18 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [markdown,goldmark,render] +signature: [".RenderString MARKUP"] +--- + +{{< new-in "0.62.0" >}} + +`.RenderString` is a method on `Page` that renders some markup to HTML using the content renderer defined for that page (if not set in the options). + +The method takes an optional map argument with these options: + +display ("inline") +: `inline` or `block`. If `inline` (default), surrounding ´
` on short snippets will be trimmed. + +markup (defaults to the Page's markup) +: See identifiers in [List of content formats](/content-management/formats/#list-of-content-formats). + +Some examples: + +```go-html-template +{{ $optBlock := dict "display" "block" }} +{{ $optOrg := dict "markup" "org" }} +{{ "**Bold Markdown**" | $p.RenderString }} +{{ "**Bold Block Markdown**" | $p.RenderString $optBlock }} +{{ "/italic org mode/" | $p.RenderString $optOrg }}:REND +``` + + +**Note** that this method is more powerful than the similar [markdownify](functions/markdownify/) function as it also supports [Render Hooks](/getting-started/configuration-markup/#markdown-render-hooks) and it has options to render other markup formats. \ No newline at end of file diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md index ff0095024..f254b9012 100644 --- a/content/en/getting-started/configuration-markup.md +++ b/content/en/getting-started/configuration-markup.md @@ -74,3 +74,62 @@ endLevel ordered : Whether or not to generate an ordered list instead of an unordered list. + + +## Markdown Render Hooks + +{{< new-in "0.62.0" >}} + +Note that this is only supported with the [Goldmark](#goldmark) renderer. + +These Render Hooks allow custom templates to render links and images from markdown. + +You can do this by creating templates with base names `render-link` and/or `render-image` inside `layouts/_default`. + +You can define [Output Format](/templates/output-formats) specific templates if needed.[^1] Your `layouts` folder may then look like this: + +```bash +layouts +└── _default + └── markup + ├── render-image.html + ├── render-image.rss.xml + └── render-link.html +``` + +Some use cases for the above: + +* Resolve link references using `.GetPage`. This would make links more portable as you could translate `./my-post.md` (and similar constructs that would work on GitHub) into `/blog/2019/01/01/my-post/` etc. +* Add `target=blank` to external links. +* Resolve (look in the page bundle, inside `/assets` etc.) and [transform](/content-management/image-processing) images. + + +[^1]: It's currently only possible to have one set of render hook templates, e.g. not per `Type` or `Section`. We may consider that in a future version. + +### Render Hook Templates + +Both `render-link` and `render-image` templates will receive this context: + +Page +: The [Page](/variables/page/) being rendered. + +Destination +: The URL. + +Title +: The title attribute. + +Text +: The link text. + +A Markdown example for a inline-style link with title: + +```md +[Text](https://www.gohugo.io "Title") +``` + +A very simple template example given the above: + +{{< code file="layouts/_default/render-link.html" >}} +{{ .Text }}{{ with .Page }} (in page {{ .Title }}){{ end }}" +{{< /code >}}