Skip to content

Latest commit

 

History

History
169 lines (116 loc) · 7.85 KB

README.md

File metadata and controls

169 lines (116 loc) · 7.85 KB
Raw

gisture

Utilizing GitHub Gists as a Blogging Platform

version

A minimal and flexible blog generator based on GitHub Gists with SEO, Templating, Syntax Highlighting, and Metadata support out-of-the-box.

Table of Contents

Features

  • 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 and robots.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.

Why Gist?

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.

Installation

$ cargo install --git https://github.com/mufeedvh/gisture.git

Install Rust/Cargo

Build From Source

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.

Usage

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.

Templating

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.

Screenshots

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.

Template Files

  • index.html - The homepage.
  • page.html - A blog/page entry.
  • page_list.html - The blog listing element.
  • 404.html - Page Not Found template.

Template Variables

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.

Modification Guide

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. :)

API Guide

Contribution

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

License

Licensed under the MIT License, see LICENSE for more information.

FAQ

  1. 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.

  1. 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.