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.

1. 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.
2. Create a new GitHub Personal Access Token with the gist scope (name can be anything you want, like "Gistblog").
3. Create a repository secret named GISTS_TOKEN and store the value of the personal access token you just created.
4. 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

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!