Rendering Content as JSON

Hugo supports JSON output out of the box too, which means you can use Hugo to create a JSON API that you can consume from other applications. Unlike RSS feeds, you need to create a layout for your JSON output, and you must specify which pages of your site should use this output type.

To explore this, you’ll make a JSON list of your project pages containing the title and URL for each project page, which you can then consume from other applications. The resulting file will look like this:

First, create a JSON template file at themes/basic/layouts/projects/list.json.

In the new template file, create a JSON template that iterates through your project pages and displays them:

Entries in a JSON array need a comma between each entry, but they don’t need a comma after the last entry. By using an index as you iterate through the entries, you can insert the comma in front of the current entry. Note that you’re using the {{- form for the templates, which suppresses whitespace in the output, depending on where the dash is located. Remember from ​Using Content Blocks and Partials​, that adding the dash after the opening braces suppresses whitespace characters in front of the output, while adding a dash in front of the closing braces suppresses whitespace that follows. Suppressing whitespace like this will result in JSON that’s more readable by humans.

Hugo won’t generate the JSON file until you configure it to do so. You can configure output formats in the main configuration file, but you can only specify that for the home page, all sections, and all content pages. To apply the output to a specific section of the site, you specify it in the front matter of the section’s page.

In this case, the output formats need to be specified in the project list content page. Edit the file content/projects/_index.md and add the following front matter to tell Hugo to generate a JSON file in addition to the HTML and XML files it generates by default:

Save the file and then run hugo server. Visit http://localhost:1313/projects/index.json and you’ll see your file.

You might be thinking that the URL is a little ugly, and you’d like to change it to /projects.json instead. The url field in a page’s front matter lets you change the URL for a page, like this:

Unfortunately, if you add that line to the content/projects/_index.md file, Hugo will no longer render the HTML page. Hugo doesn’t have a way to handle different URLs for different types. If you wanted to change the URL for your project feed, you have two options.

The first option is to configure your web server to rewrite the URL. The second (and much easier) option is to move the file before you upload it to your server. In other words, move projects/index.json to projects.json. You could do this as part of a larger build and deploy process like the one you’ll create in ​Using Webpack and npm with Hugo​.

One last thing: if you visit http://localhost:1313/projects/ and look at its source, you’ll see a <link> tag for your JSON feed next to your RSS feed. The loop you created to display your RSS feed iterates through all of the alternative formats for a page, so this JSON feed gets included.