Preview

In this example, we fetch the last 3 starred repos on Github. For each repo, we display the amount of stars and forks, the size of the repo and the last update:

Get the last starred repositories on Github with Hugo

See the demo on roneo.app for live examples.

Usage

Get the last 3 starred repositories:

{{< github-api url="https://api.github.com/users/RoneoOrg/starred?per_page=3" >}}

Get the last 5 updated repositories:

{{< github-api url="https://api.github.com/users/RoneoOrg/repos?type=owner&sort=updated&per_page=5" >}}

(Customize the amount of data with ?per_page=5)

Installation

Recommended: install as a Theme Component and get the last version.

OR paste the following code in layouts/shortcodes/github-api.html:

<ul class="github-api">
  {{ $url := .Get "url" }}
  {{ range getJSON $url }}
    {{ $p := . }}
    <li>
      <div class="github-avatar">
        <img src="{{$p.owner.avatar_url}}" alt="Avatar of {{$p.owner.login}}" title="Avatar of {{$p.owner.login}}">
      </div>
      <div class="github-name">
        <strong>
          <a href="{{ $p.html_url }}" target="_blank">{{ $p.name | humanize }}</a>
        </strong>
      </div>
        {{/*  {{ $p.full_name }}  */}}
      <div class="github-description">
        <p>{{ $p.description }}</p>
      </div>
      <div class="github-metadata">
        <small>
          Stars: {{$p.stargazers_count}} | Forks: {{$p.forks_count}} | Size: {{$p.size}} {{if $p.archived}}| Archived{{end}}<br>
          Updated at: {{substr $p.updated_at 0 10}} -  Language: {{$p.language}}
        </small>
      </div>
    </li>
    {{/*  {{ $p }}  */}}
    {{ end }}
 </ul>

Optional: add some CSS

.github-api img {
  max-height: 50px;
  float: left;
  margin: 1em;
}

.github-api li {
  background-color: #f3ebe8;
  box-shadow: 0px 1.3px 5.3px rgba(0, 0, 0, 0.028), 0px 4.5px 17.9px rgba(0, 0, 0, 0.042), 0px 20px 80px rgba(0, 0, 0, 0.07);
  border-radius: 8px 8px 0 0;
  padding: 1em;
  list-style: none;
  margin-top: 2em;
}

Done!

Customization

You can fetch any API endpoints, for example:

In some cases, you may need to identify the relevant data and customize the shortcode.

HINT: To display the complete set of data fetched from a given endpoint, use {{ $p }}

Sample output:

map[avatar_url:https://avatars.githubusercontent.com/u/1112?v=4 events_url:https://api.github.com/users/willnorris/events{/privacy} followers_url:https://api.github.com/users/willnorris/followers following_url:https://api.github.com/users/willnorris/following{/other_user} gists_url:https://api.github.com/users/willnorris/gists{/gist_id} gravatar_id: html_url:https://github.com/willnorris id:1112 login:willnorris node_id:MDQ6VXNlcjExMTI= organizations_url:https://api.github.com/users/willnorris/orgs received_events_url:https://api.github.com/users/willnorris/received_events repos_url:https://api.github.com/users/willnorris/repos

Caveats

Github API rate limits

The Github API is rate limited and the build breaks when the limit is reached.

You can ignore such errors with ignoreErrors: error-remote-getjson in your config file.
(Note that error messages are then completely hidden – no warning is displayed about rate limits reached – and empty content is retrieved and displayed).

A solution may come from Hugo cache handling. See the documentation for details.

Github account owners can increase these limits with a Github Token. This is the (advanced) solution used by Jamstack.club. Browse the source code to get some hints.

References