Custom Static Site Generator

Written in Python, Pulls Content from Github gists

This is my setup:

Use the Python libraries below. First, PyGithub does the Github work (connecting, pulling gists, pushing updates, etc) - excellent documentation here. The next two libraries allow for the Markdown in the gists to be processed with the last one being an extension for Github Flavored Markdown (my preference, but also makes sense because Github is being used - do what you will).

# IMPORT PYGITHUB (OCTOKIT)
from github import Github

# IMPORT MARKDOWN TO CONVERT GIST
import markdown

# IMPORT PY-GFM FOR GITHUB MARKDOWN STYLE
from mdx_gfm import GithubFlavoredMarkdownExtension

I recommend using a token for authentication which can be generated by going to your Github Settings > Developer Settings > Personal access tokens > Generate new token. Select your scopes as you see fit. Don't let anyone have access to your token!

Now, set variables, connect to Github, and pull gists:

# GITHUB VARIABLES
owner = 'USERNAME'
repo = 'USERNAME.github.io' # SHOULD BE GH PAGES REPO IN THIS CASE
branch = 'master'
token = 'YOUR TOKEN'

# CONNECT TO GITHUB CLIENT WITH TOKEN
ghub = Github(token)

# SET USER
user = ghub.get_user(owner)

# PULL USER GISTS
gists = user.get_gists()

Now we can start generating our content. Everyone will want to do this differently, but I'll summarize what I did and give a few tips.

  1. I recommend using a naming scheme for your gists. In my case, I set the gist description to "[Title] Description #Tag1 #Tag2" and the filename would be "ShorterTitle(#).md". Why? I use what's in the brackets as the HTML document name (so this gist would end up being an HTML file called "Title.html") as well as the link text I show in the navigation bar. I make the entire gist description searchable via some simple JavaScript code. This naming scheme also allows for easy navigation in Lepton, a gist editor. The # in the filename represents a number - this is how I order my posts. A lot of people will order by date, but this is how I chose to do it.
  2. I created templates for the index and post pages of my site. In each template I laid out the beginning HTML, CSS, and any JavaScript needed. The idea here is that for each gist, you create a copy of your post template, convert your gist from markdown to HTML, embed it, and add your closing tags. By the way, I know that there is built in functionality to embed a gist, but I ran into security issues when trying to load these on the fly. Similarly, you add a link to the new post you have created to a new copy of your index template. Once you have looped through all the gists, then you can add your closing tags for the index.

  3. I ran into issues with images - I had to store them in my Github pages repo as base64 strings and then use JavaScript to update the tags accordingly.

    ...To Be Continued...