Add Markdown diagrams and render hooks for code blocks

You can now create custom hook templates for code blocks, either one for all (`render-codeblock.html`) or for a given code language (e.g. `render-codeblock-go.html`).

We also used this new hook to add support for diagrams in Hugo:

* Goat (Go ASCII Tool) is built-in and enabled by default; just create a fenced code block with the language `goat` and start draw your Ascii diagrams.
* Another popular alternative for diagrams in Markdown, Mermaid (supported by GitHub), can also be implemented with a simple template. See the Hugo documentation for more information.

Updates #7765
Closes #9538
Fixes #9553
Fixes #8520
Fixes #6702
Fixes #9558

5 files changed, 131 insertions, 139 deletions

diff --git a/tpl/transform/init_test.go b/tpl/transform/init_test.go
deleted file mode 100644
index ec3c35897..000000000
--- a/tpl/transform/init_test.go
+++ /dev/null
@@ -1,42 +0,0 @@
-// Copyright 2017 The Hugo Authors. All rights reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package transform
-
-import (
-	"testing"
-
-	qt "github.com/frankban/quicktest"
-	"github.com/gohugoio/hugo/deps"
-	"github.com/gohugoio/hugo/htesting/hqt"
-	"github.com/gohugoio/hugo/tpl/internal"
-)
-
-func TestInit(t *testing.T) {
-	c := qt.New(t)
-	var found bool
-	var ns *internal.TemplateFuncsNamespace
-
-	for _, nsf := range internal.TemplateFuncsNamespaceRegistry {
-		ns = nsf(&deps.Deps{})
-		if ns.Name == name {
-			found = true
-			break
-		}
-	}
-
-	c.Assert(found, qt.Equals, true)
-	ctx, err := ns.Context()
-	c.Assert(err, qt.IsNil)
-	c.Assert(ctx, hqt.IsSameType, &Namespace{})
-}
diff --git a/tpl/transform/remarshal_test.go b/tpl/transform/remarshal_test.go
index 8e94ef6bf..22548593b 100644
--- a/tpl/transform/remarshal_test.go
+++ b/tpl/transform/remarshal_test.go
@@ -11,13 +11,14 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package transform
+package transform_test
 
 import (
 	"testing"
 
-	"github.com/gohugoio/hugo/config"
 	"github.com/gohugoio/hugo/htesting"
+	"github.com/gohugoio/hugo/hugolib"
+	"github.com/gohugoio/hugo/tpl/transform"
 
 	qt "github.com/frankban/quicktest"
 )
@@ -25,13 +26,14 @@ import (
 func TestRemarshal(t *testing.T) {
 	t.Parallel()
 
-	v := config.New()
-	v.Set("contentDir", "content")
-	ns := New(newDeps(v))
+	b := hugolib.NewIntegrationTestBuilder(
+		hugolib.IntegrationTestConfig{T: t},
+	).Build()
+
+	ns := transform.New(b.H.Deps)
 	c := qt.New(t)
 
 	c.Run("Roundtrip variants", func(c *qt.C) {
-
 		tomlExample := `title = 'Test Metadata'
 		
 [[resources]]
@@ -129,7 +131,6 @@ title: Test Metadata
 
 			}
 		}
-
 	})
 
 	c.Run("Comments", func(c *qt.C) {
diff --git a/tpl/transform/transform.go b/tpl/transform/transform.go
index 8ea91f234..dc7cc0342 100644
--- a/tpl/transform/transform.go
+++ b/tpl/transform/transform.go
@@ -19,6 +19,9 @@ import (
 	"html/template"
 
 	"github.com/gohugoio/hugo/cache/namedmemcache"
+	"github.com/gohugoio/hugo/common/herrors"
+	"github.com/gohugoio/hugo/markup/converter/hooks"
+	"github.com/gohugoio/hugo/markup/highlight"
 
 	"github.com/gohugoio/hugo/deps"
 	"github.com/gohugoio/hugo/helpers"
@@ -65,18 +68,28 @@ func (ns *Namespace) Highlight(s interface{}, lang string, opts ...interface{})
 		return "", err
 	}
 
-	sopts := ""
+	var optsv interface{}
 	if len(opts) > 0 {
-		sopts, err = cast.ToStringE(opts[0])
-		if err != nil {
-			return "", err
-		}
+		optsv = opts[0]
 	}
 
-	highlighted, _ := ns.deps.ContentSpec.Converters.Highlight(ss, lang, sopts)
+	hl := ns.deps.ContentSpec.Converters.GetHighlighter()
+	highlighted, _ := hl.Highlight(ss, lang, optsv)
 	return template.HTML(highlighted), nil
 }
 
+// HighlightCodeBlock highlights a code block on the form received in the codeblock render hooks.
+func (ns *Namespace) HighlightCodeBlock(ctx hooks.CodeblockContext, opts ...interface{}) (highlight.HightlightResult, error) {
+	var optsv interface{}
+	if len(opts) > 0 {
+		optsv = opts[0]
+	}
+
+	hl := ns.deps.ContentSpec.Converters.GetHighlighter()
+
+	return hl.HighlightCodeBlock(ctx, optsv)
+}
+
 // HTMLEscape returns a copy of s with reserved HTML characters escaped.
 func (ns *Namespace) HTMLEscape(s interface{}) (string, error) {
 	ss, err := cast.ToStringE(s)
@@ -100,20 +113,22 @@ func (ns *Namespace) HTMLUnescape(s interface{}) (string, error) {
 
 // Markdownify renders a given input from Markdown to HTML.
 func (ns *Namespace) Markdownify(s interface{}) (template.HTML, error) {
+	defer herrors.Recover()
 	ss, err := cast.ToStringE(s)
 	if err != nil {
 		return "", err
 	}
 
-	b, err := ns.deps.ContentSpec.RenderMarkdown([]byte(ss))
-	if err != nil {
-		return "", err
+	home := ns.deps.Site.Home()
+	if home == nil {
+		panic("home must not be nil")
 	}
+	sss, err := home.RenderString(ss)
 
 	// Strip if this is a short inline type of text.
-	b = ns.deps.ContentSpec.TrimShortHTML(b)
+	bb := ns.deps.ContentSpec.TrimShortHTML([]byte(sss))
 
-	return helpers.BytesToHTML(b), nil
+	return helpers.BytesToHTML(bb), nil
 }
 
 // Plainify returns a copy of s with all HTML tags removed.
@@ -125,3 +140,7 @@ func (ns *Namespace) Plainify(s interface{}) (string, error) {
 
 	return helpers.StripHTML(ss), nil
 }
+
+func (ns *Namespace) Reset() {
+	ns.cache.Clear()
+}
diff --git a/tpl/transform/transform_test.go b/tpl/transform/transform_test.go
index 260de5f83..3ccf1a270 100644
--- a/tpl/transform/transform_test.go
+++ b/tpl/transform/transform_test.go
@@ -11,13 +11,15 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package transform
+package transform_test
 
 import (
 	"html/template"
 	"testing"
 
 	"github.com/gohugoio/hugo/common/loggers"
+	"github.com/gohugoio/hugo/hugolib"
+	"github.com/gohugoio/hugo/tpl/transform"
 	"github.com/spf13/afero"
 
 	qt "github.com/frankban/quicktest"
@@ -32,10 +34,11 @@ type tstNoStringer struct{}
 
 func TestEmojify(t *testing.T) {
 	t.Parallel()
-	c := qt.New(t)
+	b := hugolib.NewIntegrationTestBuilder(
+		hugolib.IntegrationTestConfig{T: t},
+	).Build()
 
-	v := config.New()
-	ns := New(newDeps(v))
+	ns := transform.New(b.H.Deps)
 
 	for _, test := range []struct {
 		s      interface{}
@@ -49,23 +52,23 @@ func TestEmojify(t *testing.T) {
 
 		result, err := ns.Emojify(test.s)
 
-		if b, ok := test.expect.(bool); ok && !b {
-			c.Assert(err, qt.Not(qt.IsNil))
+		if bb, ok := test.expect.(bool); ok && !bb {
+			b.Assert(err, qt.Not(qt.IsNil))
 			continue
 		}
 
-		c.Assert(err, qt.IsNil)
-		c.Assert(result, qt.Equals, test.expect)
+		b.Assert(err, qt.IsNil)
+		b.Assert(result, qt.Equals, test.expect)
 	}
 }
 
 func TestHighlight(t *testing.T) {
 	t.Parallel()
-	c := qt.New(t)
+	b := hugolib.NewIntegrationTestBuilder(
+		hugolib.IntegrationTestConfig{T: t},
+	).Build()
 
-	v := config.New()
-	v.Set("contentDir", "content")
-	ns := New(newDeps(v))
+	ns := transform.New(b.H.Deps)
 
 	for _, test := range []struct {
 		s      interface{}
@@ -82,23 +85,23 @@ func TestHighlight(t *testing.T) {
 
 		result, err := ns.Highlight(test.s, test.lang, test.opts)
 
-		if b, ok := test.expect.(bool); ok && !b {
-			c.Assert(err, qt.Not(qt.IsNil))
+		if bb, ok := test.expect.(bool); ok && !bb {
+			b.Assert(err, qt.Not(qt.IsNil))
 			continue
 		}
 
-		c.Assert(err, qt.IsNil)
-		c.Assert(string(result), qt.Contains, test.expect.(string))
+		b.Assert(err, qt.IsNil)
+		b.Assert(string(result), qt.Contains, test.expect.(string))
 	}
 }
 
 func TestHTMLEscape(t *testing.T) {
 	t.Parallel()
-	c := qt.New(t)
+	b := hugolib.NewIntegrationTestBuilder(
+		hugolib.IntegrationTestConfig{T: t},
+	).Build()
 
-	v := config.New()
-	v.Set("contentDir", "content")
-	ns := New(newDeps(v))
+	ns := transform.New(b.H.Deps)
 
 	for _, test := range []struct {
 		s      interface{}
@@ -112,23 +115,23 @@ func TestHTMLEscape(t *testing.T) {
 
 		result, err := ns.HTMLEscape(test.s)
 
-		if b, ok := test.expect.(bool); ok && !b {
-			c.Assert(err, qt.Not(qt.IsNil))
+		if bb, ok := test.expect.(bool); ok && !bb {
+			b.Assert(err, qt.Not(qt.IsNil))
 			continue
 		}
 
-		c.Assert(err, qt.IsNil)
-		c.Assert(result, qt.Equals, test.expect)
+		b.Assert(err, qt.IsNil)
+		b.Assert(result, qt.Equals, test.expect)
 	}
 }
 
 func TestHTMLUnescape(t *testing.T) {
 	t.Parallel()
-	c := qt.New(t)
+	b := hugolib.NewIntegrationTestBuilder(
+		hugolib.IntegrationTestConfig{T: t},
+	).Build()
 
-	v := config.New()
-	v.Set("contentDir", "content")
-	ns := New(newDeps(v))
+	ns := transform.New(b.H.Deps)
 
 	for _, test := range []struct {
 		s      interface{}
@@ -142,23 +145,23 @@ func TestHTMLUnescape(t *testing.T) {
 
 		result, err := ns.HTMLUnescape(test.s)
 
-		if b, ok := test.expect.(bool); ok && !b {
-			c.Assert(err, qt.Not(qt.IsNil))
+		if bb, ok := test.expect.(bool); ok && !bb {
+			b.Assert(err, qt.Not(qt.IsNil))
 			continue
 		}
 
-		c.Assert(err, qt.IsNil)
-		c.Assert(result, qt.Equals, test.expect)
+		b.Assert(err, qt.IsNil)
+		b.Assert(result, qt.Equals, test.expect)
 	}
 }
 
 func TestMarkdownify(t *testing.T) {
 	t.Parallel()
-	c := qt.New(t)
+	b := hugolib.NewIntegrationTestBuilder(
+		hugolib.IntegrationTestConfig{T: t},
+	).Build()
 
-	v := config.New()
-	v.Set("contentDir", "content")
-	ns := New(newDeps(v))
+	ns := transform.New(b.H.Deps)
 
 	for _, test := range []struct {
 		s      interface{}
@@ -171,23 +174,24 @@ func TestMarkdownify(t *testing.T) {
 
 		result, err := ns.Markdownify(test.s)
 
-		if b, ok := test.expect.(bool); ok && !b {
-			c.Assert(err, qt.Not(qt.IsNil))
+		if bb, ok := test.expect.(bool); ok && !bb {
+			b.Assert(err, qt.Not(qt.IsNil))
 			continue
 		}
 
-		c.Assert(err, qt.IsNil)
-		c.Assert(result, qt.Equals, test.expect)
+		b.Assert(err, qt.IsNil)
+		b.Assert(result, qt.Equals, test.expect)
 	}
 }
 
 // Issue #3040
 func TestMarkdownifyBlocksOfText(t *testing.T) {
 	t.Parallel()
-	c := qt.New(t)
-	v := config.New()
-	v.Set("contentDir", "content")
-	ns := New(newDeps(v))
+	b := hugolib.NewIntegrationTestBuilder(
+		hugolib.IntegrationTestConfig{T: t},
+	).Build()
+
+	ns := transform.New(b.H.Deps)
 
 	text := `
 #First 
@@ -202,17 +206,18 @@ And then some.
 `
 
 	result, err := ns.Markdownify(text)
-	c.Assert(err, qt.IsNil)
-	c.Assert(result, qt.Equals, template.HTML(
+	b.Assert(err, qt.IsNil)
+	b.Assert(result, qt.Equals, template.HTML(
 		"<p>#First</p>\n<p>This is some <em>bold</em> text.</p>\n<h2 id=\"second\">Second</h2>\n<p>This is some more text.</p>\n<p>And then some.</p>\n"))
 }
 
 func TestPlainify(t *testing.T) {
 	t.Parallel()
-	c := qt.New(t)
+	b := hugolib.NewIntegrationTestBuilder(
+		hugolib.IntegrationTestConfig{T: t},
+	).Build()
 
-	v := config.New()
-	ns := New(newDeps(v))
+	ns := transform.New(b.H.Deps)
 
 	for _, test := range []struct {
 		s      interface{}
@@ -225,13 +230,13 @@ func TestPlainify(t *testing.T) {
 
 		result, err := ns.Plainify(test.s)
 
-		if b, ok := test.expect.(bool); ok && !b {
-			c.Assert(err, qt.Not(qt.IsNil))
+		if bb, ok := test.expect.(bool); ok && !bb {
+			b.Assert(err, qt.Not(qt.IsNil))
 			continue
 		}
 
-		c.Assert(err, qt.IsNil)
-		c.Assert(result, qt.Equals, test.expect)
+		b.Assert(err, qt.IsNil)
+		b.Assert(result, qt.Equals, test.expect)
 	}
 }
 
diff --git a/tpl/transform/unmarshal_test.go b/tpl/transform/unmarshal_test.go
index fb0e446c3..2b14282ec 100644
--- a/tpl/transform/unmarshal_test.go
+++ b/tpl/transform/unmarshal_test.go
@@ -11,7 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package transform
+package transform_test
 
 import (
 	"fmt"
@@ -19,7 +19,8 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/gohugoio/hugo/config"
+	"github.com/gohugoio/hugo/hugolib"
+	"github.com/gohugoio/hugo/tpl/transform"
 
 	"github.com/gohugoio/hugo/common/hugio"
 	"github.com/gohugoio/hugo/resources/resource"
@@ -80,12 +81,14 @@ func (t testContentResource) Key() string {
 }
 
 func TestUnmarshal(t *testing.T) {
-	v := config.New()
-	ns := New(newDeps(v))
-	c := qt.New(t)
+	b := hugolib.NewIntegrationTestBuilder(
+		hugolib.IntegrationTestConfig{T: t},
+	).Build()
+
+	ns := transform.New(b.H.Deps)
 
 	assertSlogan := func(m map[string]interface{}) {
-		c.Assert(m["slogan"], qt.Equals, "Hugo Rocks!")
+		b.Assert(m["slogan"], qt.Equals, "Hugo Rocks!")
 	}
 
 	for _, test := range []struct {
@@ -116,24 +119,24 @@ func TestUnmarshal(t *testing.T) {
 		}},
 		{testContentResource{key: "r1", content: `1997,Ford,E350,"ac, abs, moon",3000.00
 1999,Chevy,"Venture ""Extended Edition""","",4900.00`, mime: media.CSVType}, nil, func(r [][]string) {
-			c.Assert(len(r), qt.Equals, 2)
+			b.Assert(len(r), qt.Equals, 2)
 			first := r[0]
-			c.Assert(len(first), qt.Equals, 5)
-			c.Assert(first[1], qt.Equals, "Ford")
+			b.Assert(len(first), qt.Equals, 5)
+			b.Assert(first[1], qt.Equals, "Ford")
 		}},
 		{testContentResource{key: "r1", content: `a;b;c`, mime: media.CSVType}, map[string]interface{}{"delimiter": ";"}, func(r [][]string) {
-			c.Assert([][]string{{"a", "b", "c"}}, qt.DeepEquals, r)
+			b.Assert([][]string{{"a", "b", "c"}}, qt.DeepEquals, r)
 		}},
 		{"a,b,c", nil, func(r [][]string) {
-			c.Assert([][]string{{"a", "b", "c"}}, qt.DeepEquals, r)
+			b.Assert([][]string{{"a", "b", "c"}}, qt.DeepEquals, r)
 		}},
 		{"a;b;c", map[string]interface{}{"delimiter": ";"}, func(r [][]string) {
-			c.Assert([][]string{{"a", "b", "c"}}, qt.DeepEquals, r)
+			b.Assert([][]string{{"a", "b", "c"}}, qt.DeepEquals, r)
 		}},
 		{testContentResource{key: "r1", content: `
 % This is a comment
 a;b;c`, mime: media.CSVType}, map[string]interface{}{"DElimiter": ";", "Comment": "%"}, func(r [][]string) {
-			c.Assert([][]string{{"a", "b", "c"}}, qt.DeepEquals, r)
+			b.Assert([][]string{{"a", "b", "c"}}, qt.DeepEquals, r)
 		}},
 		// errors
 		{"thisisnotavaliddataformat", nil, false},
@@ -144,7 +147,7 @@ a;b;c`, mime: media.CSVType}, map[string]interface{}{"DElimiter": ";", "Comment"
 		{tstNoStringer{}, nil, false},
 	} {
 
-		ns.cache.Clear()
+		ns.Reset()
 
 		var args []interface{}
 
@@ -156,29 +159,32 @@ a;b;c`, mime: media.CSVType}, map[string]interface{}{"DElimiter": ";", "Comment"
 
 		result, err := ns.Unmarshal(args...)
 
-		if b, ok := test.expect.(bool); ok && !b {
-			c.Assert(err, qt.Not(qt.IsNil))
+		if bb, ok := test.expect.(bool); ok && !bb {
+			b.Assert(err, qt.Not(qt.IsNil))
 		} else if fn, ok := test.expect.(func(m map[string]interface{})); ok {
-			c.Assert(err, qt.IsNil)
+			b.Assert(err, qt.IsNil)
 			m, ok := result.(map[string]interface{})
-			c.Assert(ok, qt.Equals, true)
+			b.Assert(ok, qt.Equals, true)
 			fn(m)
 		} else if fn, ok := test.expect.(func(r [][]string)); ok {
-			c.Assert(err, qt.IsNil)
+			b.Assert(err, qt.IsNil)
 			r, ok := result.([][]string)
-			c.Assert(ok, qt.Equals, true)
+			b.Assert(ok, qt.Equals, true)
 			fn(r)
 		} else {
-			c.Assert(err, qt.IsNil)
-			c.Assert(result, qt.Equals, test.expect)
+			b.Assert(err, qt.IsNil)
+			b.Assert(result, qt.Equals, test.expect)
 		}
 
 	}
 }
 
 func BenchmarkUnmarshalString(b *testing.B) {
-	v := config.New()
-	ns := New(newDeps(v))
+	bb := hugolib.NewIntegrationTestBuilder(
+		hugolib.IntegrationTestConfig{T: b},
+	).Build()
+
+	ns := transform.New(bb.H.Deps)
 
 	const numJsons = 100
 
@@ -200,8 +206,11 @@ func BenchmarkUnmarshalString(b *testing.B) {
 }
 
 func BenchmarkUnmarshalResource(b *testing.B) {
-	v := config.New()
-	ns := New(newDeps(v))
+	bb := hugolib.NewIntegrationTestBuilder(
+		hugolib.IntegrationTestConfig{T: b},
+	).Build()
+
+	ns := transform.New(bb.H.Deps)
 
 	const numJsons = 100