Including Bible Passages in Hugo

I have a few posts in my mind that will need me to include bible passages in the pages. I could just quote them, but that is no fun and I am happy make a lot of effort to be lazy.

I am using Hugo to power this site, so I decided I would add a shortcode that would allow me to do it via an API. There are a few decisions to be made first.

First I needed to decide what my data source would be. There are a couple of options:

• Bible Gateway is probably the best known, but they only allow embedding an iFrame. That feels a little 2002, so I rejected that idea.
• YouVersion is the bible app that everyone I know uses on mobile and has every version under the sun. Sadly they do not have a public API so that was a no go.
• ESV.org has an API which is really nice so I decided to use that. That means that I am locked into the ESV. I tend to use the NIV, but that is not a deal breaker, so I happy with that.

I am sure there are other APIs out there, but once I found the ESV one I stopped looking.

This API needs a key for authentication, which I do not want to commit to source control. So I set an environment variable called HUGO_ESV_API_KEY with my API key in it. Locally I do this using direnv and the deployment pipeline is a Gitlab CI variable.

My next decision was when I should render the passage. Build time or load time? I prefer to do it at build time so the client just gets HTML/CSS and everyone is happy.

After a bit of digging around in the docs (and also a smattering of ChatGPT) I ended up with the following in layout/shortcodes/esv.html:

And some CSS in assets/css/custom.css to make it look nice:

Now, when I want to include a verse I can simply use:

and it will render like this:

13 I write these things to you who believe in the name of the Son of God, that you may know that you have eternal life. 14 And this is the confidence that we have toward him, that if we ask anything according to his will he hears us.

(ESV)

Now I have a simple way to include bible passages in my site. This is not limited purely to bible passages though. You can use the same pattern to include anything from an API at build time.

• Bible
• Christianity