{
  "$type": "site.standard.document",
  "description": "feat: add Plotly graphing shortcodes and JSON support to Hugo",
  "path": "/posts/plotly-graphing-in-hugo/",
  "publishedAt": "2024-08-01T00:00:00.000Z",
  "site": "https://read.ryancowl.es",
  "tags": [
    "Code"
  ],
  "textContent": "import PlotlyChart from '@/components/PlotlyChart.vue'\n\nI’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.\n\nI 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.\n\n  \n\n⏳ Conditionally load the script\n\nFirst, 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.\n\nLet’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:\n\n📂 :\n\n 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:\n\nWith , the script will be loaded and we’re ready to use it on our page. The question now is how best to do so.\n\n  \n\n💻 Create a Plotly shortcode\n\nHugo 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.\n\n📂 :\n\nThis 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.\n\nI also added some basic error handling and included a few Plotly configuration options which can be removed or modified as well.\n\n  \n\n📊 Get some data\n\nWith 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 [](https://plotly.com/python-api-reference/generated/plotly.io.writejson.html) to return the  needed to create a simple graph.\n\nThis 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.\n\n  \n\n📈 Insert the shortcode into a post or page:\n\nWe’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:\n\n🥁 Drum roll…\n\n🎉 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 :\n\nTo 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:\n\n📂 :\n\nAnd we’ll get something like this:\n\nSource: As union membership declines, income inequality increases_\n\nThere 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!\n📚 References and Further Reading\nPlotly with Hugo\nPlotly Figure Sample\nPlotly Configuration Options in JavaScript",
  "title": "How to Use the Plotly Graphing Library in Hugo"
}