hugo/tpl/tplimpl/template_funcs.go
Bjørn Erik Pedersen 08fdca9d93 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
2022-02-24 18:59:50 +01:00

207 lines
6 KiB
Go

// Copyright 2017-present The Hugo Authors. All rights reserved.
//
// Portions Copyright The Go Authors.
// 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 tplimpl
import (
"context"
"reflect"
"strings"
"github.com/gohugoio/hugo/tpl"
"github.com/gohugoio/hugo/common/maps"
template "github.com/gohugoio/hugo/tpl/internal/go_templates/htmltemplate"
texttemplate "github.com/gohugoio/hugo/tpl/internal/go_templates/texttemplate"
"github.com/gohugoio/hugo/deps"
"github.com/gohugoio/hugo/tpl/internal"
// Init the namespaces
_ "github.com/gohugoio/hugo/tpl/cast"
_ "github.com/gohugoio/hugo/tpl/collections"
_ "github.com/gohugoio/hugo/tpl/compare"
_ "github.com/gohugoio/hugo/tpl/crypto"
_ "github.com/gohugoio/hugo/tpl/data"
_ "github.com/gohugoio/hugo/tpl/debug"
_ "github.com/gohugoio/hugo/tpl/diagrams"
_ "github.com/gohugoio/hugo/tpl/encoding"
_ "github.com/gohugoio/hugo/tpl/fmt"
_ "github.com/gohugoio/hugo/tpl/hugo"
_ "github.com/gohugoio/hugo/tpl/images"
_ "github.com/gohugoio/hugo/tpl/inflect"
_ "github.com/gohugoio/hugo/tpl/js"
_ "github.com/gohugoio/hugo/tpl/lang"
_ "github.com/gohugoio/hugo/tpl/math"
_ "github.com/gohugoio/hugo/tpl/openapi/openapi3"
_ "github.com/gohugoio/hugo/tpl/os"
_ "github.com/gohugoio/hugo/tpl/partials"
_ "github.com/gohugoio/hugo/tpl/path"
_ "github.com/gohugoio/hugo/tpl/reflect"
_ "github.com/gohugoio/hugo/tpl/resources"
_ "github.com/gohugoio/hugo/tpl/safe"
_ "github.com/gohugoio/hugo/tpl/site"
_ "github.com/gohugoio/hugo/tpl/strings"
_ "github.com/gohugoio/hugo/tpl/templates"
_ "github.com/gohugoio/hugo/tpl/time"
_ "github.com/gohugoio/hugo/tpl/transform"
_ "github.com/gohugoio/hugo/tpl/urls"
)
var (
_ texttemplate.ExecHelper = (*templateExecHelper)(nil)
zero reflect.Value
contextInterface = reflect.TypeOf((*context.Context)(nil)).Elem()
)
type templateExecHelper struct {
running bool // whether we're in server mode.
funcs map[string]reflect.Value
}
func (t *templateExecHelper) GetFunc(ctx context.Context, tmpl texttemplate.Preparer, name string) (fn reflect.Value, firstArg reflect.Value, found bool) {
if fn, found := t.funcs[name]; found {
if fn.Type().NumIn() > 0 {
first := fn.Type().In(0)
if first.Implements(contextInterface) {
// TODO(bep) check if we can void this conversion every time -- and if that matters.
// The first argument may be context.Context. This is never provided by the end user, but it's used to pass down
// contextual information, e.g. the top level data context (e.g. Page).
return fn, reflect.ValueOf(ctx), true
}
}
return fn, zero, true
}
return zero, zero, false
}
func (t *templateExecHelper) Init(ctx context.Context, tmpl texttemplate.Preparer) {
}
func (t *templateExecHelper) GetMapValue(ctx context.Context, tmpl texttemplate.Preparer, receiver, key reflect.Value) (reflect.Value, bool) {
if params, ok := receiver.Interface().(maps.Params); ok {
// Case insensitive.
keystr := strings.ToLower(key.String())
v, found := params[keystr]
if !found {
return zero, false
}
return reflect.ValueOf(v), true
}
v := receiver.MapIndex(key)
return v, v.IsValid()
}
func (t *templateExecHelper) GetMethod(ctx context.Context, tmpl texttemplate.Preparer, receiver reflect.Value, name string) (method reflect.Value, firstArg reflect.Value) {
if t.running {
// This is a hot path and receiver.MethodByName really shows up in the benchmarks,
// so we maintain a list of method names with that signature.
// TODO(bep) I have a branch that makes this construct superflous.
switch name {
case "GetPage", "Render":
if info, ok := tmpl.(tpl.Info); ok {
if m := receiver.MethodByName(name + "WithTemplateInfo"); m.IsValid() {
return m, reflect.ValueOf(info)
}
}
}
}
fn := receiver.MethodByName(name)
if !fn.IsValid() {
return zero, zero
}
if fn.Type().NumIn() > 0 {
first := fn.Type().In(0)
if first.Implements(contextInterface) {
// The first argument may be context.Context. This is never provided by the end user, but it's used to pass down
// contextual information, e.g. the top level data context (e.g. Page).
return fn, reflect.ValueOf(ctx)
}
}
return fn, zero
}
func newTemplateExecuter(d *deps.Deps) (texttemplate.Executer, map[string]reflect.Value) {
funcs := createFuncMap(d)
funcsv := make(map[string]reflect.Value)
for k, v := range funcs {
vv := reflect.ValueOf(v)
funcsv[k] = vv
}
// Duplicate Go's internal funcs here for faster lookups.
for k, v := range template.GoFuncs {
if _, exists := funcsv[k]; !exists {
vv, ok := v.(reflect.Value)
if !ok {
vv = reflect.ValueOf(v)
}
funcsv[k] = vv
}
}
for k, v := range texttemplate.GoFuncs {
if _, exists := funcsv[k]; !exists {
funcsv[k] = v
}
}
exeHelper := &templateExecHelper{
running: d.Running,
funcs: funcsv,
}
return texttemplate.NewExecuter(
exeHelper,
), funcsv
}
func createFuncMap(d *deps.Deps) map[string]interface{} {
funcMap := template.FuncMap{}
// Merge the namespace funcs
for _, nsf := range internal.TemplateFuncsNamespaceRegistry {
ns := nsf(d)
if _, exists := funcMap[ns.Name]; exists {
panic(ns.Name + " is a duplicate template func")
}
funcMap[ns.Name] = ns.Context
for _, mm := range ns.MethodMappings {
for _, alias := range mm.Aliases {
if _, exists := funcMap[alias]; exists {
panic(alias + " is a duplicate template func")
}
funcMap[alias] = mm.Method
}
}
}
if d.OverloadedTemplateFuncs != nil {
for k, v := range d.OverloadedTemplateFuncs {
funcMap[k] = v
}
}
return funcMap
}