Hugo: Custom template function development and use

[jmitchell]

Is there a recommended way to develop and use custom template functions similar to highlight without having to maintain a fork or get them merged into Hugo?

I'm happy to share any custom template functions I make, but sometimes template functions are very project-specific and need to be implemented or changed quickly. The rapid iteration offered by shortcodes is great, but it leaves me confined to the template language. I found myself needing the additional flexibility offered by template functions (see example below). Unfortunately the barriers to maintaining my own custom template functions is high enough to make me think twice about using them.

Are there plans to add a plug-in system for custom template functions that have no business being merged into Hugo? I haven't worked with Go templates or thought about this enough to fully envision how this might work. Perhaps people could maintain their own template function repos that adhere to some plug-in interface, and when such repos are listed in a project's config those custom templates will be made available to Hugo. Or to keep things really simple, we could make a some new built-in template functions like

1. run-script: synchronously call a shell script with arbitrary arguments
2. inject-file: locate file at the specified path and inject its contents here

As an aside, when a template function or shortcode layout is invoked there's no obvious way to tell which kind it is. For instance, somebody could make a highlight shortcode layout and expect both it and the built-in template to work. Off-hand, I'm not sure how Hugo would handle this. In any case, encouraging custom template function development increases the risk of naming collisions. It may help to somehow distinguish template function calls from shortcode calls. As it stands I imagine you're wary about accepting pull requests for new template functions.

Example 1: rendering an image using via a language/processor

I want a page to generate and display a graph which is described using the DOT language.

{{% graphviz-figure %}}
digraph G {Hello->World}
{{% /graphviz-figure %}}

...should turn into...

There are two critical steps:

1. run a script like echo $INNER | dot -Tpng > static/img/${NAME}.png
2. inject <img src='img/${NAME}.png' /> into the page's HTML

Example 2: inject HTML produced by an arbitrary program

I have access to a stand-alone program that translates an obscure document format into HTML. I also have one such document stored in document.xyz. How can I get Hugo to run the stand-alone program on document.xyz and inject the HTML output, either from a file or STDOUT, into my Hugo page?

[spf13]

I'm happy to share any custom template functions I make, but sometimes template functions are very project-specific and need to be implemented or changed quickly.

Great, please share. I think you'd be surprised what other people may find valuable. That said too many functions loaded do affect performance so there is a tradeoff here.

Are there plans to add a plug-in system for custom template functions that have no business being merged into Hugo?

No. I don't see how this would work given that Go doesn't support dynamically loading libraries.

to keep things really simple, we could make a some new built-in template functions like
run-script: synchronously call a shell script with arbitrary arguments
inject-file: locate file at the specified path and inject its contents here

I think this idea has merit and could work well.

For instance, somebody could make a highlight shortcode layout and expect both it and the built-in template to work.... It may help to somehow distinguish template function calls from shortcode calls.

Shortcodes and template functions are completely isolated. They would both work. Template functions only exist in the templates. Shortcodes only exist in the markdown.

I have access to a stand-alone program that translates an obscure document format into HTML. I also have one such document stored in document.xyz. How can I get Hugo to run the stand-alone program on document.xyz and inject the HTML output, either from a file or STDOUT, into my Hugo page?

Hugo's design allows for many different source filetypes to be handled. It should be fairly easy to add support for alternative formats. For example someone already contributed support for RST, which shells out similarly to how you are describing.

As I feel this is a question which is now answered, I'll close the ticket. Please add to it if you want further clarification, or feel free to send me a PR or file a new issue for a specific feature.

[Xeoncross]

Hugo will eventually be able to use dynamic libs (.so) using the new Go 1.8 plugins system: https://nick.groenen.me/posts/2017/01/09/plugins-in-go-18/

[moorereason]

Thanks for your enthusiasm, but...

Please don't comment on issues that were closed 3 years ago. Also, please don't make assumptions that Hugo will support dynamic linking when the Hugo team has never said we intend to do so (I'm actually against this idea). And, finally, please don't promise features for a project you've never contributed to.

[Xeoncross]

I don't understand the complaint about commenting on old issues (helps avoid duplicating issues and discussions).

However, I do realize that what I wrote could be interpreted as promising a feature. I did not mean it that way, I was simply saying that the option will exist once enough of the community runs go 1.8+.