Pulling Data from Remote Sources
You’re not limited to using local data. You can use Hugo to fetch remote data and process it every time you build the site.
Let’s create a page of the site that shows your public GitHub repositories.
To get that data, you will use the GitHub API and then make a request to https://api.github.com/users/<your username>/repos. This returns a JSON collection of all your repositories and doesn’t require any authorization.
Store the API URL and your GitHub username in the site’s configuration file, rather than directly in the layout. Open config.toml and add two new fields to the params section to hold these values:
| | [params] |
| | author = "Brian Hogan" |
| | description = "My portfolio site" |
| | |
| » | gh_url = "https://api.github.com/users" |
| » | gh_user = "your-gh-user" |
Then, create a layout for this file in themes/basic/layouts/_default/opensource.html. Unlike the contact page you created, you’ll keep this with your theme. Add the usual boilerplate to the file:
| | {{ define "main" }} |
| | <h2>{{ .Title }}</h2> |
| | |
| | {{ .Content }} |
| | {{ end }} |
Next, right after the {{ .Content }} line, add the following line of code to build up the GitHub URL using your username from the site’s configuration:
| | {{ $url := printf "%s/%s/repos" .Site.Params.gh_url .Site.Params.gh_user }} |
This defines a $url variable and uses Go’s printf function to concatenate the base URL, your username, and the /repos endpoint. Note that you have to use .Site.Params as a prefix on both of these, as you stored them in the site’s configuration.
Now, add this line to make the request for the JSON file using the $url variable you built:
| | {{ $repos := getJSON $url }} |
This makes the request and fetches the JSON data into a collection that works like the other collections you’ve used. From here, you can use the range function and iterate over the results. Each result has a name, url, html_url, and description property, so use those to build a list of your repositories, like this:
| | <section class="oss"> |
| | {{ range $repos }} |
| | <article> |
| | <h3><a href="{{ .html_url }}">{{ .name }}</a></h3> |
| | <p>{{ .description }}</p> |
| | </article> |
| | {{ end }} |
| | </section> |
The html_url property points to the URL of the repository, while the url property points to the API endpoint, which you could use if you wanted to fetch even more details about each project.
Every time you rebuild the site, Hugo will make a request to the GitHub API and pull in this data. Since the data about your repositories doesn’t change that often, this level of caching is perfect. However, if you don’t want to hit the API every time you build, you can download the JSON data, store it in your data directory, and load it in like you did with your social media links on the contact. If you take this approach, remember to refresh your local file periodically.
Next, create a new content page for your site called opensource.md which will use this layout. Stop the development server and use the hugo new command to create this file:
| | $ hugo new opensource.md |
Open the newly created content/opensource.md file in your editor. Ensure the draft status is false, set the title to “Open Source Software”, and ensure it uses the opensource layout. Below the front matter, add a paragraph of content that introduces the page content. Your completed file should look like this:
| | --- |
| | title: "Open Source Software" |
| | date: 2020-01-01T13:35:47-05:00 |
| | draft: false |
| | layout: opensource |
| | --- |
| | |
| | My Open Source Software on GitHub: |
Let’s add some CSS to transform the list into a series of tiles. Open themes/basic/static/css/style.css and add the following code:
| | .oss { |
| | display: flex; |
| | flex-wrap: wrap; |
| | justify-content: space-between; |
| | } |
| | |
| | .oss article { |
| | border: 1px solid #ddd; |
| | box-shadow: 3px 3px 3px #ddd; |
| | margin: 0.5%; |
| | padding: 0.5%; |
| | width: 30%; |
| | } |
Flexbox once again comes to the rescue. The oss container becomes the flex container and specifies that child elements should wrap and be spaced out equally. The inner article elements get a width, margin, a border and a small drop shadow. The result is a series of tiles nicely spaced apart.
Ensure all of your files are saved and start up the development server with hugo server. Visit http://localhost:1313/opensource and you’ll see your projects displayed as tiles as shown in the screenshot.
Now, whenever you create a new project on GitHub, it’ll show up when you regenerate the site.
Hugo is a static site generator that converts existing content documents into web pages. It doesn’t have any built-in ability to generate content pages from data, but you can still make it work.
For example, you could write a small script that reads the data and generates Markdown documents, which it stores in the content folder. Then, when you run hugo to build the site, the generated pages will be included.
Hugo’s developers want Hugo to stay focused on fast website generation. As a result, you’ll often find that you’ll rely on tools outside of Hugo for more complex situations.
Before moving on, add the link to your open source projects page to your project list page. Open themes/basic/layouts/projects/list.html and add the link on the page like this, along with its summary:
| | <section class="projects"> |
| » | <section class="project"> |
| » | {{ with .Site.GetPage "/opensource.md" }} |
| » | <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3> |
| » | <p>{{ .Summary }}</p> |
| » | {{ end }} |
| » | </section> |
Instead of using a hard-coded link, you’re grabbing the title and URL from the page using Hugo’s GetPage function, which takes the path to the Markdown file. Using this method, you can pull data from any page into your layouts.
The front matter for the open source page doesn’t have a summary field, so you’re probably wondering where the summary will come from. Hugo gets it by reading in the first few sentences of the content for that page. You’ll take more control of auto-generated summaries in Chapter 5, Adding a Blog.
Visit http://localhost:1313/projects to see your open source projects displayed above the other projects:
So far you’ve used Hugo to generate HTML pages, but you can also generate other formats too.