Upload source

Author: mufeedvh

Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "gisture"
+version = "0.1.0"
+edition = "2018"
+
+[dependencies]
+cacache = "9.0.0"
+chrono = "0.4.19"
+clap = "2.33.3"
+colored = "2.0.0"
+futures = "0.3.17"
+handlebars = "4.1.3"
+html-escape = "0.2.9"
+html-minifier = "3.0.14"
+lol_html = "0.3.0"
+once_cell = "1.8.0"
+portpicker = "0.1.1"
+pulldown-cmark = "0.8.0"
+serde = { version = "1.0.130", features = ["derive"] }
+serde_json = "1.0.68"
+sitemap = "0.4.1"
+syntect = "4.6.0"
+tokio = { version = "1.12.0", features = ["full"] }
+ureq = { version = "*", features = ["json"] }
+warp = "0.3.1"
+
+[profile.release]
+lto = "thin"
+panic = "abort"

README.md

@@ -0,0 +1,166 @@
+<h1 align="center"><code>gisture</code></h1>
+<h4 align="center">Utilizing GitHub Gists as a Blogging Platform</h4>
+<p align="center">
+	<img src="https://img.shields.io/badge/version-0.1.0-blue.svg" title="version" alt="version">
+	<a href="https://github.com/mufeedvh/gisture/blob/master/LICENSE"><img alt="GitHub license" src="https://img.shields.io/github/license/mufeedvh/gisture.svg"></a>
+</p>
+
+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](#features)
+- [Why Gist?](#why-gist)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Templating](#templating)
+- [Modification Guide](#modification-guide)
+- [Contribution](#contribution)
+- [License](#license)
+- [FAQ](#faq)
+
+## 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](#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](http://www.sublimetext.com/docs/3/syntax.html#include-syntax). (Thanks to [syntect](https://github.com/trishume/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](https://github.com/raphlinus/pulldown-cmark) which supports GitHub flavored elements.
+
+## Installation
+
+    $ cargo install --git https://github.com/mufeedvh/gisture
+    
+[Install Rust/Cargo](https://rust-lang.org/tools/install)
+
+## Build From Source
+
+**Prerequisites:**
+
+* [Git](https://git-scm.org/downloads)
+* [Rust](https://rust-lang.org/tools/install)
+* 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.
+
+### 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. :)
+
+- [Markdown Parser Options](https://github.com/mufeedvh/gisture/blob/master/src/parsers.rs#L115-L123)
+- [HTML Rewriting/Handling](https://github.com/mufeedvh/gisture/blob/master/src/parsers.rs#L49-L90)
+- [Add New Configuration Options](https://github.com/mufeedvh/gisture/blob/master/src/config.rs#L11-L36)
+- [Gist User Data](https://github.com/mufeedvh/gisture/blob/master/src/gist.rs#L14-L22)
+- [Gist Entry Data](https://github.com/mufeedvh/gisture/blob/master/src/gist.rs#L149-L156)
+- [Disk Caching](https://github.com/mufeedvh/gisture/blob/master/src/cache.rs#L6-L35)
+- [SEO Function Utils](https://github.com/mufeedvh/gisture/blob/master/src/metadata.rs#L21-L24)
+- [Syntax Highlighting Theme](https://github.com/mufeedvh/gisture/blob/master/src/parsers.rs#L45)
+
+### API Guide
+
+- [User's Gists](https://docs.github.com/en/rest/reference/gists#list-gists-for-a-user)
+- [Single Gist](https://docs.github.com/en/rest/reference/gists#get-a-gist)
+- [Gist Revision](https://docs.github.com/en/rest/reference/gists#get-a-gist-revision)
+- [Gist Comments](https://docs.github.com/en/rest/reference/gists#list-gist-comments)
+
+## 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 <a href="https://github.com/mufeedvh/gisture/blob/master/LICENSE">LICENSE</a> for more information.
+
+## FAQ
+
+1. Why?
+
+> This is the embodiment of the [automation XKCD comic](https://xkcd.com/1319/), 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](https://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.
+
+2. 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.
+
+## Liked the project?
+
+Support the author by buying him a coffee!
+
+<a href="https://www.buymeacoffee.com/mufeedvh" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="45" width="170"></a>
+
+---

gisture.json

@@ -0,0 +1,9 @@
+{
+  "github_username": "octocat",
+  "blog_title": "John Wick's Pencil",
+  "blog_description": "Rusty, I Guess.",
+  "blog_url": "https://blog.johnwickspencil.com/",
+  "pages_title": "{{ blog_title }} | John Wick's Pencil",
+  "minify_html": false,
+  "show_comments": true
+}

src/.extras/banner

@@ -0,0 +1,8 @@
+       _     _                  
+      (_)   | |                 
+  __ _ _ ___| |_ _   _ _ __ ___ 
+ / _` | / __| __| | | | '__/ _ \
+| (_| | \__ \ |_| |_| | | |  __/
+ \__, |_|___/\__|\__,_|_|  \___|
+  __/ |
+ |___/  v0.1.0

src/cache.rs

@@ -0,0 +1,35 @@
+use std::path::Path;
+
+use cacache;
+
+#[derive(Debug, Clone)]
+pub(crate) struct Cache {
+    pub permalink_key: String,
+    pub updated_at: String,
+}
+
+// NOTE: cache function calls are blocked (forced sync)
+impl Cache {
+    /// Save a blog entry to disk cache
+    pub async fn save_cache_entry(&self) -> Result<(), cacache::Error> {
+        let cache_dir = String::from("./gisture_cache");
+
+        cacache::write(&cache_dir, &self.permalink_key, self.updated_at.as_bytes()).await?;
+
+        Ok(())
+    }
+
+    /// Check if a blog entry is cached on disk
+    pub async fn is_cached(&self) -> Result<bool, cacache::Error> {
+        let cache_dir = String::from("./gisture_cache");
+        let data = cacache::read(&cache_dir, &self.permalink_key).await?;
+
+        let build_file = Path::new(&format!("public/{}", &self.permalink_key)).exists();
+
+        if data == self.updated_at.as_bytes() && build_file {
+            Ok(true)
+        } else {
+            Ok(false)
+        }
+    }
+}

src/cli.rs

@@ -0,0 +1,19 @@
+use clap::{App, Arg, ArgMatches};
+
+pub fn interface() -> ArgMatches<'static> {
+    App::new("gisture")
+        .version("0.1.0")
+        .author("Mufeed VH <[email protected]>")
+        .about("A minimal and light-weight blog generator based on GitHub gists.")
+        .arg(Arg::with_name("COMMAND")
+            .help("`build` compiles all your gists to HTML pages.\n`serve` launches a web server to preview the generated pages.")
+            .value_name("build | serve")
+            .required(false)
+            .index(1))
+        .arg(Arg::with_name("PORT")
+            .help("PORT to run the preview server on (comes after the `serve` command).")
+            .value_name("PORT")
+            .required(false)
+            .index(2))
+        .get_matches()
+}

src/config.rs

@@ -0,0 +1,101 @@
+use std::fs::File;
+use std::io::prelude::*;
+use std::io::BufReader;
+use std::path::Path;
+use std::process::exit;
+
+use serde::{Deserialize, Serialize};
+
+use crate::messages::{push_message, Type};
+
+#[derive(Serialize, Deserialize)]
+pub(crate) struct Config {
+    pub github_username: String,
+    pub blog_title: String,
+    pub blog_description: String,
+    pub blog_url: String,
+    pub pages_title: String,
+    pub minify_html: bool,
+    pub show_comments: bool,
+}
+
+static CONFIG_FILE: &str = "gisture.json";
+
+impl Config {
+    pub fn default() -> Self {
+        // default config file values
+        Self {
+            github_username: "octocat".into(),
+            blog_title: "John Wick's Pencil".into(),
+            blog_description: "Rusty, I Guess.".into(),
+            blog_url: "https://blog.johnwickspencil.com/".into(),
+            pages_title: "{{ blog_title }} | John Wick's Pencil".into(),
+            minify_html: false,
+            show_comments: true,
+        }
+    }
+
+    /// Generate a boilerplate config file
+    pub fn generate_default() {
+        if !Path::new(CONFIG_FILE).exists() {
+            let json_config = match serde_json::to_string_pretty(&Self::default()) {
+                Ok(json_config) => json_config,
+                Err(error) => {
+                    let message = format!("Failed to serialize JSON config: \n\t{}", error);
+                    push_message(Type::Error, &message);
+                    exit(1)
+                }
+            };
+            let mut config_file = match File::create(CONFIG_FILE) {
+                Ok(file) => file,
+                Err(error) => {
+                    let message = format!("Failed to create config file: \n\t{}", error);
+                    push_message(Type::Error, &message);
+                    exit(1)
+                }
+            };
+            match config_file.write_all(json_config.as_bytes()) {
+                Ok(()) => (),
+                Err(error) => {
+                    let message = format!("Failed to write to config file: \n\t{}", error);
+                    push_message(Type::Error, &message);
+                    exit(1)
+                }
+            }
+        }
+    }
+
+    /// Fetch config values from `gisture.json`
+    pub fn get_config() -> Self {
+        let file = match File::open(CONFIG_FILE) {
+            Ok(file) => file,
+            Err(error) => {
+                let message = format!("Failed to open config file: \n\t{}", error);
+                push_message(Type::Error, &message);
+                exit(1)
+            }
+        };
+
+        let mut buf_reader = BufReader::new(file);
+        let mut user_config = String::new();
+        match buf_reader.read_to_string(&mut user_config) {
+            Ok(_) => (),
+            Err(error) => {
+                let message = format!("Failed while reading config file: \n\t{}", error);
+                push_message(Type::Error, &message);
+                exit(1)
+            }
+        }
+
+        let config: Config = match serde_json::from_str(&user_config) {
+            Ok(config) => config,
+            Err(error) => {
+                let message = format!("Failed while serializing user config: \n\t{}", error);
+                push_message(Type::Error, &message);
+                exit(1)
+            }
+        };
+
+        config
+    }
+}