Introduction

Today (June 14, 2021) I answered a question on Stackoverflow regarding the Google Cloud Recommender API that required Python source code. I also created a GitHub Gist to make downloading the code easier. That got me thinking about how to display a Gist on a Laravel page. A Google search showed nothing that I could develop or learn from. This article is the results of experimenting with GitHub Gists and Laravel.

The final result is a one-line directive @gist that will display a GitHub Gist in a view.

Creating a GitHub Gist with the CLI

It is easy to publish a file as a public Gist. GitHub recently released the GitHub CLI which makes publishing a Gist a single line command.

Command syntax:

Options:

Example:

I put the code for my answer in the file recommender_example.py and published it with this command:

Now, I have a public Gist. How do I display it?

Method #1 – Embedded Script

Click on the Gist URL. Above the gist is the option to grab the “Embed” script. For my gist the scripts is:

Let’s put that script into a basic HTML file and test. Start with a basic HTML 5 template and modify it as shown below. Notice the script tag at line 10. Save the following HTML as test1.html and display it in your browser. For Windows, from the Command Prompt, start test1.html

Method #2 – Fetch Gist JSON

If you append .json to the end of a GitHub Gist URL, JSON is returned with details on the Gist. For example, load this URL into your browser:

This returns the following JSON. Note that I have truncated the <div> portion to make the JSON readable.

Two of the keys are important:

  • stylesheet – This is the CSS markup that GitHub provides to beautify the HTML.
  • div – This is raw HTML to display on your page.

Let’s write a simple PHP program to read the JSON and output an HTML page. Copy the following code to index.php.

Start the built-in web server:

Start a web browser and go to http://localhost:8000/

Method #3 – Simple Laravel View Blade

Laravel blades support the @php directive to support PHP code. Let’s put together a simple view and a route to that view. The GitHub Gist is hardcoded in this example. Save this page to /resources/views/method3.blade.php. In this example, the Gist is a simple two-line file to simplify testing.

Edit /routes/web.php and add the following route:

when developing, clear the route cache after each route change:

Start the Laravel built-in development server:

Start a web browser and go to http://localhost:8000/method3

We can enhance this by passing the gist URL as data to the view:

Route:

Method #4 – Custom Directive

You can define your own custom directives using the directive method. In this example, we will extend Laravel with the @gist directive.

Edit app/Providers/AppServiceProvider.php and include the following code:

Now you can display a Gist with a directive in the view. Put the following line in a new file /resources/views/method4.blade.php

Create a route:

Each time you modify AppServiceProvider.php or the view, clear the view cache:

Start a web browser and go to http://localhost:8000/method4

Controlling Gist Width and Height

Use the following CSS as a starter for controlling the height and width of a Gist:

Listing a user’s public Gists

GitHub offers an API to list a user’s public Gists. Let’s test this using curl and jq. The API returns a lot of information. We are interested in the public URL. This example sends the JSON output to jq to parse the public URL.

List gists for a user

You will need the user’s username. In my case it is jhanley-com. The username is easy to find. Find a user’s repository or Gist and the username is in the URL. Example for Google: https://github.com/google.

Example output:

Summary

Once you understand how to display a Gist in a view, it is easy to style the Gist by wrapping it with HTML and CSS. You can control placement, width, height, and more easily.