Introducing Gistblog 🎉: Blog your little ❤️ out using GitHub Gists

Josh Campbell — Tue, 07 Dec 2021 00:43:48 +0000

Hey there and thanks for stopping by! For the the #ActionsHackathon21 I created something... that definitely belongs in the Whacky Wildcard category! I'd like to introduce you to...

Gistblog is an opinionated GitHub repo setup that turns markdown into blog posts. Powered by the Gistblog GitHub Action, your markdown is turned into wonderful GitHub Gists that can be easily updated and shared. Here's my Gistblog embedded into my GitHub profile README. The fancy markdown table of blog posts is even generated by the Gistblog Action too! Read on for more details about how you can start Gistblogging!

My Workflow

Please see the official Gistblog repository for the latest instructions on using Gistblog! tl;dr This is the GitHub Actions workflow that does all the heavy lifting, and this is the GitHub Action I created to handle creating/updating the Gists.

Getting setup with Gistblog

As I mentioned, Gistblog follows an opinionated setup in order to function. Please read the below carefully to get started.

Create a new repo or use an existing repo. Create two directories in the root of your repo: a blog/ directory and a GitHub Actions workflow directory .github/workflows/ if it doesn't already exist.
Create a new GitHub Personal Access Token with the gist scope (name can be anything you want, like "Gistblog").
Create a repository secret named GISTS_TOKEN and store the value of the personal access token you just created.
Create .github/workflows/gistblog.yaml with the following GitHub Actions workflow. Be sure to change your branch name below if it isn't main:

name: Gistblog
on:
  push:
    branches:
      - main
jobs:
  gistblog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: dorny/paths-filter@v2
        id: blog
        with:
          list-files: shell
          filters: |
            create_blog:
            - added: 'blog/*.md'
            update_blog:
            - modified: 'blog/*.md'
      - if: steps.blog.outputs.create_blog == 'true'
        uses: seajoshc/gistblog-action@v1
        with:
          gists-token: ${{ secrets.GISTS_TOKEN }}
          operation: create
          blog-files: "${{ steps.blog.outputs.create_blog_files }}"
      - if: steps.blog.outputs.update_blog == 'true'
        uses: seajoshc/gistblog-action@v1
        with:
          gists-token: ${{ secrets.GISTS_TOKEN }}
          operation: update
          blog-files: "${{ steps.blog.outputs.update_blog_files }}"

In the spirit of the #ActionsHackathon21, you can see I'm taking advantage of the checkout action GitHub provides and the Paths Filter action by dorny to create the desired workflow. I'm also using the Gistblog Action I created for this hackathon which handles managing all the blog posts as Gists. I'd like to explore Composite actions soon to see if I can reduce all of this to a single action making setup even easier.

How to blog with Gistblog

Gistblog simply looks for new, or updated, markdown (.md) files in the blog/ directory of your repo each time you push to main. If there are new files, Gistblog will automatically create new Gists for your blog posts. And each time you update a file the Gist gets updated too. Each Gist/blog post is backed by a permanent link that you can share out. It's that easy!

Ideally, you set a description for each blog post by declaring

<!--
post_description: Example Post Title: A short description goes here. 
-->

at the top of each markdown file, like in this example. Link previews look a bit nicer when you use this description format.

Gistblog also maintains a Table of Contents(ToC) for all your blog posts. The ToC gets updated each time Gistblog runs so it's always up to date. Check your Gists to find your ToC. Try putting the markdown table from your ToC into your GitHub Profile README to share your blog with the innerwebz. This is a manual process for now but I'll be looking to solve that in the future!

If you've got assets, like images, create blog/assets/ and keep your files there. To include them in your post, you'll need to use the URL of where they will end up once pushed into your repo as the image source. The URL is predictable based on the file name and your GitHub username: https://raw.githubusercontent.com/<github_username>/<repo_name>/main/blog/assets/<filename>.<extension>. See this example.

Changing the filenames on any Gists created by Gistblog will result in duplicate blog posts next time you update. It's best not to touch anything on the Gists really.

Happy Gistblogging! 🎉

Submission Category:

Wacky Wildcards

Yaml File or Link to Code

seajoshc / gistblog

Blog your little ❤️ out using GitHub Gists.

Gistblog - Blog your little ❤️ out using GitHub Gists.

Do you need a simple platform for sharing your thoughts and ideas with the internet? Have you ever wanted an easy way to turn some plaintext into a blog post? Don't care about things like SEO, monetization, or having a fancy looking website? Is "indefinitely free" your desired monthly cost of hosting your own blog where all the content is yours? Already a big GitHub fan? Gistblog is the blogging engine for you!

Because Gistblog is an opinionated framework, please read…

View on GitHub

seajoshc / gistblog-action

Blog your little ❤️ out using GitHub Gists.

Gistblog Action

The Gistblog GitHub Action is part of an opinionated setup that lets you use GitHub Gists as a blogging engine. I strongly urge you to read this first. You can also checkout this blogpost for more info about Gistblog.

Inputs

This action expects three things in order: a GitHub Personal Access Token with "gist" scope, either the "create" or "update" command, and a space delimited list of blog post (markdown) files to process. Create a secret within the repo you're using named GISTS_TOKEN and store the value of the aforementioned personal access token. The secret can be securely accessed as shown in the below examples.

gists-token

description: A valid GitHub Personal Access Token with "gist" scope.
required: true

operation

description: The operation to perform either "create" or "update".
required: true

blog-files

description: A space delimited list of files to process.
required: true

Outputs

None.

Example usage

As…

View on GitHub

Additional Resources / Info

You can see my personal Gistblog here and a table of all my posts using Gistblog here.

Why does this exist????

Why Gists when you can blog on DEV? Yeah that's a bit awkward 😅 But it's all good, I'm entering the Whacky Wildcards category 🤣 A short backstory...

I don't quite know what triggered it but one night in early November 2021 I decided that I wanted to start blogging every once in awhile again. It doesn't matter that few, if any, people will ever read the things I write. It's just a creative outlet. But regardless, as always I was paralyzed by all the choices I had for which blog platform/engine to use. I decided to just put my first post in a GitHub Gist to get the ball rolling, thinking I would move it elsewhere later. But then I thought it might be kind of cool to continue using Gists for blogging since it was so easy. I started looking more into the APIs and discovered that a workflow around blogging via Gists was definitely feasible. It also just so happened that the 2021 GitHub Actions Hackathon was going on, so as any good developer does... I decided to make my own ~~Rube Goldberg machine~~ blog engine instead of trying to pick one! A few weeks later I am happy to introduce... Gistblog!

DEV Community: Josh Campbell

Introducing Gistblog 🎉: Blog your little ❤️ out using GitHub Gists

My Workflow

Getting setup with Gistblog

How to blog with Gistblog

Submission Category:

Yaml File or Link to Code

seajoshc / gistblog

Blog your little ❤️ out using GitHub Gists.

Gistblog - Blog your little ❤️ out using GitHub Gists.

seajoshc / gistblog-action

Blog your little ❤️ out using GitHub Gists.

Gistblog Action

Inputs

gists-token

operation

blog-files

Outputs

Example usage

Additional Resources / Info

Why does this exist????