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

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!

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 the below instructions carefully.

Setup

1. You may fork this repo, create a new repo, or use an existing repo. If you didn't fork this 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. If you forked this repo, you will need to enable the provided workflow by going into the "Actions" menu within your fork and accept the warning about running the workflow. If you didn't fork this repo, 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 }}"

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 my example.md. 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 my example.md.

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! 🎉