HUGO

The long-overdue need for converting/outputting other formats

Call it by many names: Issue 796, “exec feature,” “convert X to Y,” or some permutation of such…

Hugo, in my opinion, while utterly AMAZING in so many ways, still suffers from one big gap…any form of extensibility to handle formats other than Markdown input (minus a few of the special-case external helper exec input types), with HTML/AMP/RSS output (minus some image manipulation capability).

I’ve been using Hugo for a while, having moved to it from other home-built publication engines that leveraged Markdown to publish static sites. In my time with static site generation, I’ve always needed the ability to handle conversion of content other than MD->HTML. Always.

And given the recurring nature of the requests in Github issues, or here in discourse.gohugo, I’d say there continues to be a need in the Hugo user community for some sort of feature akin to “exec”/#796 at least for specific content handling.

In my own world, working with sites publishing content that include complicated documents (Hugo does wonderfully here!) in need of images (Hugo does fine here) AND diagrams (Hugo won’t handle Graphviz, Draw.io, or Mermaid content unless first converted to an image format and then put in place in the Hugo folders), I find that I am constantly working to find ways around the fact that Hugo simply refuses to assist me in managing that content.

And in that world of mine, I’m working to publish static sites collaboratively with a large group of authors, none of them strong technical writers, none of them intricately versed in the internals of web publishing. Markdown does a great job of making them focus on content, not format. Images do a good job of accentuating their documents. And then, without fail, they need diagrams.

And all the diagramming options I have available…all of them are in formats that integrate well with a Markdown-friendly editor. DOT and Mermaid both are text-based, and edited directly with a text editor. They both can also be previewed dynamically real-time. Draw.io has the ability to plug in to VSCode as a native window and develop its drawio files quickly and easily. But none of these formats are handled well by Hugo.

So my authors spend time manually editing links (the conversion handled with my pre-Hugo CI/CD work I’ve done) and worrying that they are appropriately linking a .gv/.dot/.drawio file in their document. Invariably they eventually make mistakes. But they never make a mistake with a Markdown file that is handled well natively by the publication engine, whose link is retrievable in a standardized fashion.

Sure, we can write pre-Hugo scripts. We can develop additional CI/CD tools to handle these use cases. And in doing so, live without the power that Hugo offers for link management and ease of authoring, for a significant portion of just about any modern site I’ve worked on.

I get the security risks. I do. I get the performance risks. I do. But I also am real-world enough to know that the need is there, and the code is possible.

I’ve already written some of this code.

So far, I’ve written my own internal Hugo functions and related shortcodes for handling Mermaid and Graphviz inline content. Took lessons from the pandoc (and other) exec-based “helpers” and implemented a GV/DOT->SVG conversion. It at this time dumps to an HTML file, as writing the logic in the file output was more than I wanted to take on without having this conversation I’m starting here.

I’m happy to devise a fleshed out version of this code. One than handles source->target mapping in config, has “safe” exec handling similar to current exec handling for Pandoc and the like, and allows for configuration only insomuch as it relates to controlling output format (GV->SVG/PNG, Draw.io->PDF/SVG/PNG, etc).

And if this is seen as unacceptable in the core content logic…can we have a serious discussion around how we might extend Hugo Modules to allow me or someone else to write the module that would provide for that custom content handling that would allow for these all-too-common use cases?

Before I commit this effort, it would be nice to know that it won’t be left to sit alongside the other exec/796 conversations and enhancement issue requests…going nowhere fast.

And if nothing comes of this effort…I guess I’m left with authoring a pre-Hugo helper…for me and for all those people who continue to have real-world needs beyond MD->HTML and image resizing.

Thanks for all the amazing that Hugo is and can do! Much appreciated!

Thanks,
Jason

1 Like

Since this got zero traction or discussion…and since a fork to integrate such a capability is beyond the scope of how much effort I want to put into maintaining such a solution…

I’ve created a pre-processor helper for use in CI/CD deployment with Hugo.

The design intent is to provide for a single tool that will execute file-tree walks on the Hugo files, performing user defined processes on the files that match a pattern.

So, for example, for all Draw.io files found, execute a command to convert it to an SVG.

This code is barely out of alpha. It is nowhere near perfect or well documented. But it exists, and will improve as I have time or others submit PRs.

1 Like