A minimal and flexible blog generator based on GitHub Gists with SEO, Templating, Syntax Highlighting, and Metadata support out-of-the-box.
- Single Binary - Just run the binary and it will generate the starter boilerplate.
- Simple Configuration - A simple JSON file will be created upon initiation which has everything you need to setup your blog.
- Templating - A set of template variables are prefixed to write your own blog template or port any blog theme easily using everyone's familiar Handlebars. (See Templating)
- SEO Utility - A
sitemap.xml
androbots.txt
are automatically generated according to your gist entries. - Syntax Highlighting - Every code snippet in your Gist will be highlighted in the generated HTML and you can add your own syntax spec with Sublime Text syntax definitions. (Thanks to syntect)
- Helpful Log Messages - Every error case has been handled with a helpful and verbose error message to provide a breeze CLI experience.
- Caching - Since Gists are fetched from the API, building multiple blog entries will take time hence gisture handles a disk cache and only build when a gist is updated.
Here are some of the concepts that made me utilize/choose GitHub Gists:
- Git: You can use git to edit and manage a gist just like a repository.
- Hosting: Your Gists will exist as long as GitHub exists.
- Integrated Comment Section: Every gist has a comment section which supports Markdown.
- Transparent: As it's based on gists, anyone can check revisions to see the changes made to a blog entry.
- Starring: You can bookmark a gist entry into your GitHub account by starring it.
Also GitHub's Markdown editor is pretty cool and gisture uses pulldown-cmark which supports GitHub flavored elements.
$ cargo install --git https://github.com/mufeedvh/gisture.git
Prerequisites:
- Git
- Rust
- Cargo (Automatically installed when installing Rust)
- A C linker (Only for Linux, generally comes pre-installed)
$ git clone https://github.com/mufeedvh/gisture.git
$ cd gisture/
$ cargo build --release
The first command clones this repository into your local machine and the last two commands enters the directory and builds the source in release mode.
A gisture blog should have xyz.blog.md
as it's Gist filename where /xyz
becomes the permalink, description as it's meta description
, a Markdown title (# Title
) for it's title
.
Setup configuration and Generate template boilerplate:
$ gisture
Build blog files with the configuration:
$ gisture build
Open up a preview web server on port 1337
:
$ gisture serve 1337
Just running serve
will open up the web server on a random free port.
gisture uses Handlebars as it's templating engine. All you need to make/port a theme for your blog, are these files and a couple of template variables which are automatically generated upon initiation.
Here are some screenshots of the basic starter template. Admittedly it's not shiny and it's just made for demonstration purposes, the starter templates will show you how to use the template variables or port another theme to support gisture.
![]() |
![]() |
![]() |
index.html
- The homepage.page.html
- A blog/page entry.page_list.html
- The blog listing element.404.html
- Page Not Found template.
NOTE: Just refer to the templates/
directory to get up and running quickly, it has a starter template that utilizes these variables.
Blog:
{{ blog_title }}
- The home title of the blog.{{ blog_description }}
- The home description of the blog.{{ blog_url }}
- The URL of the blog.{{ blog_list }}
- The list of all the blog/page entries as an HTML element. (blog_list.html
)
Gist:
{{ page_title }}
- A blog/page entry's title.{{ page_description }}
- A blog/page entry's description.{{ page_url }}
- The full URL of a blog/page entry.{{ published_date }}
- The published datetime of a blog/page entry.{{ updated_at }}
- The recent update datetime of a blog/page entry.{{ blog_contents }}
- The content of the blog/page entry.
Here are some code pointers if you want to modify gisture to fit your own needs or to add new features. I have tried to make the code verbose and easier to modify. :)
- Markdown Parser Options
- HTML Rewriting/Handling
- Add New Configuration Options
- Gist User Data
- Gist Entry Data
- Disk Caching
- SEO Function Utils
- Syntax Highlighting Theme
Ways to contribute:
- Suggest a feature
- Report a bug
- Fix something and open a pull request
- Help me document the code
- Spread the word
- Create a better starter template for gisture because I suck at CSS
Licensed under the MIT License, see LICENSE for more information.
- Why?
This is the embodiment of the automation XKCD comic, all I wanted to do was write a blog (which I didn't) and this is the result. I am not a fan of static site generators because of the markdown metadata section the disqus comment hosting shenanigans (I don't like disqus) although utteranc.es is pretty cool. So I set out to find another static solution and ended up deciding to utilize Gist as a blogging platform because it comes with my favorite Markdown editor, an excellent comment section, starring for bookmarks and hence the yoink. Hopefully someone other than me who actually wants to write a blog finds it useful so putting it out there.
- Why are the Handlebars variables unescaped?
It's Markdown converted to HTML so it needs to be unescaped and one does not simply XSS their own blog.