How to Use the Plotly Graphing Library in Hugo

import PlotlyChart from '@/components/PlotlyChart.vue'

I’ve recently been using the Plotly Graphing Library for Python to experiment with simple data visualization. As I continue to learn more about Hugo, I thought it would be fun to see if I could bring the two together and find a way to display figures generated with Plotly on my Hugo site.

I found that Plotly can export charts and graphs as JSON. Knowing this, I can use Python to manipulate data locally, generate visualizations with Plotly, and then export the figures as to display on my Hugo site. Still with me? I’m just as surprised as you are! Let’s dig in.

⏳ Conditionally load the script

First, we’ll need to load the Plotly script on pages where we want to display a chart or graph. We don’t need this scipt to load on pages where it’s not required, so we can include it conditionally and only call it when needed. We can use a corresponding parameter in our content’s front matter to handle this.

Let’s create (or modify) the file in to load the Plotly script. Plotly provides a minified version of the latest script on their CDN, so we can use that and wrap it in a Go template conditional:

📂 :

will look for the parameter in a content file’s front matter. If it’s present and set to , the script will be loaded. Now when editing content on our site we can load the script only on pages that require it. As an example, the front matter of this post currently contains:

With , the script will be loaded and we’re ready to use it on our page. The question now is how best to do so.

💻 Create a Plotly shortcode

Hugo Shortcodes allow us to create small, reusable snippets that we can embed within our site. Since we most likely want to create multiple graphs, shortcodes provide a great solution for our intended use case. We can abstract out the rendering logic and then simply pass the desired into each shortcode to be displayed. I found a helpful reference that I shamelessly stole from referenced to create the new shortcode.

📂 :

This shortcode will take the file path and a few optional parameters to fetch and render the Plotly graph. The graph will be wrapped in a new . If an is not specified within the shortcode then one will be generated with which generates a timestamp down to the millisecond to ensure each graph’s parent has a unique to avoid potential conflicts.

I also added some basic error handling and included a few Plotly configuration options which can be removed or modified as well.

📊 Get some data

With our script loaded and the shortcode ready to display a graph, we just need to find some data to feed it. For this example, I created a Jupyter Notebook and used to return the needed to create a simple graph.

This will create a file that can be passed to the shortcode to display the graph on our Hugo site. I copied this file to a subdirectory within this post’s parent directory here: . Now we just need to put it all together.

📈 Insert the shortcode into a post or page:

We’ve got our data and we’re ready to take our new shortcode for a test drive. Our shortcode includes a few optional parameters but the only thing we need to throw at it is some . Let’s keep it simple and stick with the defaults for now and insert our shortcode like so:

🥁 Drum roll…

🎉 We have hypothetical fruit! I’m not sure what I’ll do with 14 oranges, but that’s a problem for another time. Back to the shortcode, we can further customize the basic layout of each graph that is inserted by passing the optional parameters. Let’s specify a height, width, and custom ID for the parent :

To share a more practical example than hypothetical fruits, I borrowed some numbers from the Economic Policy Institute. I used them to recreate my own take on their graph using Plotly’s Python library. I exported that chart as following similar steps as above and now I can insert that graph with the following:

📂 :

And we’ll get something like this:

Source: As union membership declines, income inequality increases_

There we have it. With the heavy lifting done, we can now export Plotly graphs as and display them on our Hugo site with a simple shortcode. I’ve included some references below for further reading and would be thrilled to hear any feedback or suggestions you have on this approach! 📚 References and Further Reading Plotly with Hugo Plotly Figure Sample Plotly Configuration Options in JavaScript