Introducing the GitHub Widget Plugin for Nikola
Tags: nikola, nikolagithubwidget, opensource, projects
Published: 2024-07-05 06:19:20

---
title: Introducing the GitHub Widget Plugin for Nikola
published: true
date: 2024-07-04 07:00:00 UTC
tags: nikola,nikolagithubwidget,opensource,projects
canonical_url: https://diegocarrasco.com/introducing-github-widget-plugin/
---

![](https://diegocarrasco.com/images/social-images/introducing-github-widget-plugin.jpg)

 

- [TL;DR](https://diegocarrasco.com/introducing-github-widget-plugin/#tldr)
- [Context](https://diegocarrasco.com/introducing-github-widget-plugin/#context)
- [How It Works](https://diegocarrasco.com/introducing-github-widget-plugin/#how-it-works)
  - [Installation](https://diegocarrasco.com/introducing-github-widget-plugin/#installation)
  - [Optional Configuration](https://diegocarrasco.com/introducing-github-widget-plugin/#optional-configuration)
  - [Using the Shortcode](https://diegocarrasco.com/introducing-github-widget-plugin/#using-the-shortcode)
  - [Customization](https://diegocarrasco.com/introducing-github-widget-plugin/#customization)
- [Visual Examples](https://diegocarrasco.com/introducing-github-widget-plugin/#visual-examples)
  - [CSS Customization](https://diegocarrasco.com/introducing-github-widget-plugin/#css-customization)
- [Conclusion](https://diegocarrasco.com/introducing-github-widget-plugin/#conclusion)
- [References](https://diegocarrasco.com/introducing-github-widget-plugin/#references)

### TL;DR

The GitHub Widget Shortcode Plugin for Nikola lets you embed a customizable widget showcasing a GitHub repository's details in your site.

### Context

Today, I'm excited to announce that my GitHub Widget Plugin for Nikola has been merged! This plugin allows you to embed a GitHub repository widget directly into your Nikola-generated site, displaying key details of the repository.

Nikola is a static site generator that offers great flexibility. I've already written about it [a few times](https://diegocarrasco.com/categories/nikola/, and it's what's powers this site. However, embedding GitHub repository details required custom solutions—until now. My new plugin provides an easy way to integrate this functionality using a simple shortcode.

Why is this important? Because somehow I've been using GitHub more for public code, such as my [espanso](https://espanso.org/)-compatible [TextExpander Android App](https://github.com/dacog/textexpander_android). Thus, I plan to have a section on this site to list such projects, and I was missing a way to show updated information from each repository.

With this shortcode I can just do this [listing-github-widget-example.md](https://diegocarrasco.com/listings/listing-github-widget-example.md.html)[(Source)](https://diegocarrasco.com/listings/listing-github-widget-example.md)

```
{{% github_widget %}}dacog/textexpander_android {{%/github_widget %}}`

```

 and I get the following

[![NamedUser(login=](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)](https://github.com/dacog/textexpander_android)

[
#### textexpander\_android
](https://github.com/dacog/textexpander_android)

This is a basic text expander app for android. Use it as a espanso companion app, as it parses the yaml files in espanso/match

**Languages:** Kotlin

- ⭐ Stars: 9
- <svg aria-hidden="true" height="16" viewbox="0 0 16 16" version="1.1" width="16" data-view-component="true">
    <path d="M9.5 3.25a2.25 2.25 0 1 1 3 2.122V6A2.5 2.5 0 0 1 10 8.5H6a1 1 0 0 0-1 1v1.128a2.251 2.251 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.5 0v1.836A2.493 2.493 0 0 1 6 7h4a1 1 0 0 0 1-1v-.628A2.25 2.25 0 0 1 9.5 3.25Zm-6 0a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Zm8.25-.75a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5ZM4.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z"></path>
</svg> Forks: 1
- 👁 Watchers: 2
- ❗ Open Issues: 0

This looks a lot better than just a link 😁

### How It Works

It was a bit trial and error, as I had not used the GitHub API before.

The first approach was to use `requests` to call the api endpoints (such as `https://api.github.com/repos/{repo}/commits`) to get the json response and use that. But after that I also wanted to get the latest commits and the latest release, if available. And then I got an api rate limit error, with a nice message:

```
{
"message": "API rate limit exceeded for 2.206.40.62. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
"documentation\_url": "https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting"
}

```

That meant, of course, that I now had to get a token to avoid the error. I tried following the GitHub API Documentation for AUTH, but without success. And then it got me... there should already be a library for this... and there was.

I installed [PyGithub](https://github.com/PyGithub/PyGithub) and refactored my code to use it. That meant I removed most of my code, as I no longer had to call each endpoint on my own.

Authentication worked instantly and I no longer had the api rate limit error.

That's the short story. Now let's explain how to use this.

#### Installation

You need to have a working nikola setup. If you dont have one, you can check this article: link://slug/nikola-blog-setup

To install the plugin, run the following command:

```
nikola plugin -i github_widget

```

#### Optional Configuration

For enhanced API usage, add your GitHub API token to `conf.py`:

```
# Add your GitHub API token here
GITHUB\_API\_TOKEN = 'your\_github\_api\_token\_here'

```

This step is optional but recommended to avoid API rate limit issues.

Your personal token should allow access to the repositories and its contents. Read-only permission is enough.

#### Using the Shortcode

Here are some examples of how to use the shortcode in your markdown files:

[listing-github-widget-examples.md](https://diegocarrasco.com/listings/listing-github-widget-examples.md.html)[(Source)](https://diegocarrasco.com/listings/listing-github-widget-examples.md)

```
// Basic Example
{{% github_widget %}}user/repo{{% /github_widget %}}

// Example with Avatar and Custom Width
{{% github_widget avatar=true max_width=400px %}}user/repo{{% /github_widget %}}

// Example with Latest Release and Commit Info
{{% github_widget avatar=true latest_release=true latest_commit=true max_width=400px %}}user/repo{{% /github_widget %}}

```

#### Customization

You can customize the widget to display various details such as the repository owner's avatar, the latest release, and the latest commit. Adjust the `max_width` parameter to fit the widget into your site's layout.

### Visual Examples

Here's what the widgets look like with the example shortcodes:

**Basic Example**

![Basic Example](https://diegocarrasco.com/images/github-widget/example-1.png)

**With Avatar and Custom Width**

![With Avatar](https://diegocarrasco.com/images/github-widget/example-2.png)

**With Latest Release and Commit Info**

![With Latest Info](https://diegocarrasco.com/images/github-widget/example-3.png)

#### CSS Customization

To style the widget, you can use the following CSS:

```
/\* github shortcode \*/
.github-widget {
display: flex;
align-items: center;
border: 1px solid #ddd;
padding: 10px;
margin: 10px 0;
border-radius: 5px;
background-color: #f9f9f9;
}

.github-widget-image {
margin-right: 10px;
}

.github-widget img {
border-radius: 50%;
}

.github-widget .repo-info {
display: flex;
flex-direction: column;
}

.github-widget .repo-info h3 {
margin: 0;
font-size: 1.2em;
}

.github-widget .repo-info p {
margin: 5px 0;
font-size: 0.9em;
color: #555;
}

.github-widget .repo-info ul {
list-style: none;
padding: 0;
display: flex;
gap: 10px;
}

.github-widget .repo-info ul li {
font-size: 0.8em;
color: #333;
}

.github-widget h4 {
color: black;
}

```

### Conclusion

The GitHub Widget Plugin for Nikola makes it easy to display detailed information about any GitHub repository on your site. With simple configuration and usage, it's a great addition for any developer's blog or project page.

### References

- [Nikola Documentation](https://getnikola.com/extending.html)
- [GitHub API Documentation](https://docs.github.com/en/rest)
- [PyGithub](https://github.com/PyGithub/PyGithub)