Hugo: Use Environment Variable in Markdown Files

Hugo is a fantastic framework to generate static site from markdown and serve them. Using environment variables in templates is a breeze but using them in markdown files can be a bit tricky. You need to use custom shortcodes as workaround to resolve this issue.

What is shortcodes

Now the question comes, what is shorcode? From Hugo’s documentation:

Shortcodes can access page variables and also have their own specific built-in variables.

Meaning you can use this to access different variables like from config file or you can write your own shortcodes to provide your custom variables. We will be using both to access environment variables. Let us see how to create custom shortcodes. This shortcodes will be used in markdown files.

Custom shortcodes

First, you need to create a new folder named shortcodes inside the layouts directory. Inside that, you need to create a template which will be treated as a shortcode. For example, if you create layouts/shortcodes/abc.html, then you can access variables inside home_dir.html in markdown files via {{< home_dir >}}. The folder structure will look like this:

Hugo Project
├── content
├── layouts
│   └── shortcodes
│      ├── home_dir.html
│      └── custom_dir.html
├── static
├── themes
└──config.toml

More information can be found in hugo’s documentation.

Use environment variable in shortcodes

Now it is time to use environment variables in these shortcodes. There are two ways you can achieve this.

By getenv variable

You can use getenv in the shortcodes. For example, if you write {{ getenv "HOME" }} in home_dir.html then, if you use {{< home_dir >}} in markdown, it should render the home directory name in rendered pages.

By site variable

You can directly access site-level variables(or global variables) in shortcodes. For that, first you need to declare them in config.toml(or json or other formats):

theme = "your theme"
baseURL = "/"
[params]
  homeDir = "/home/arnab"

Then in home_dir.html, you can write:

{{ .Site.Params.homeDir }}

Finally, if you want to provide your environment variable as homeDir, then pass it as argument when running hugo server:

env HUGO_PARAMS_homeDir=${HOME} hugo server

Or if you want to generate the html files, then run:

env HUGO_PARAMS_homeDir=${HOME} hugo

In conclusion

It is very easy to use environment variables in markdown using Hugo. Although there are many debates on if you should use them or not. That is why there is no straight forward process to do it in Hugo.

Thank you for reading. If you have any questions or queries, please use the comment section below.

Last updated: Apr 05, 2024