Insen

Write, Code, Dream, Travel, Play !

© 2018. All rights reserved. Personal opinions. Hefty pinches of salt !!.

site based on hyde by @mdo

'Not all those who wander are lost' - J.R.R Tolkien

Blogging with Github Pages and Pretzel.

29 Aug 2017

As I mentioned in my 'hello-blog' post, my search for blogging tools ended at Github Pages and Pretzel. In this post, I will outline the process of setting up a blog using Github pages, Pretzel, Hyde and Markdown, using what I learnt while setting up this one.

The Goal.

The goal here is a system which has the following publish-a-blog sequence -

Essentially, its very developer friendly. This process emulates the code, build, test, deploy cycle of software development.

The Pieces.

The infrastructure

(Note - If you don't have a github account, this is a good time to create one. Also, if you don't know Git, much of this blog won't make sense to you. if you really, really want to blog, this is a good alternative option tumblr).

Github and Github Pages

Github Pages are a feature inbuilt into Github which enables you to host static web-sites with minimum effort. There are a few different flavors.

User Pages

If your github account is acc, Create a new repository named as acc (same as the account name). A public web-site with no content is available at http://acc.github.io.

Add a index.html with only the text 'Hello World' into the 'master' branch. You should see 'Hello World' in your browser from http://acc.github.io/.

Organization Pages

Similar to user pages except the repo is at the organization level, and has the same name as the organization. Gets published(approximately) at http://github.com/organizationname. *Check with official Github documentation as I didn't investigate this much.

Project Pages

If your github account is acc, viz, your Github account is at https://acc.github.com, and you add a new repository named as repo, the Project pages site with no content is available at https://acc.github.io/repo

Add a folder called 'docs' in repo in the master branch.

Add a index.html with just the text 'Hello World' into the 'docs' folder. This automatically gets published as http://acc.github.io/repo. You should see 'Hello World' in your browser from this site.

These sites are available at a per-repository level. They can also be configured so that the web-site is geing served either from master branch, from a top level folder in the master branch named as docs or a branch specifically named as gh-pages.

I am using the docs option above.

Other Things...

Note that it is perfectly possible to have user-pages, organization-pages and project-pages in the same account. Given that the user account is acc, the organization name is organizationname, and the project repo name is repo, the following public web-sites will be available. - http://acc.github.io/ as the User Page Site. - http://github.com/organizationname as an Organization Page Site - http://acc.github.io/repo as a Project Page Site

The site can be a Jekyll based, OR a plain vanilla html website but with with an index.html at the top level of the site. I presume how this works is this - Github passes a http call to the site url through a web-server which can process Liquid - a html templating engine. This engine passes on plain vanilla html as is, so html spec based content just flows through that web server. We are using this approach as we are pre-building the web-site as a collection of static html pages.

If using Jekyll, you need to create a Jekyll based website in the repo and branch as per your choice from the page types - user, organization or project. Github's Jekyll based build process will probably do the Jekyll builds on your behalf before publishing online. More details about Github's inbuilt support for Jekyll publishing can be found at here.

Hello Pretzel (and Static-site generators)!

Pretzel is a open source, static-site generator in .NET.

Maybe the first question to address is how many of these there are? Take a look. When it comes to frameworks, We are living in a world of plenty these days.

What do they do? Well, basically a static site generator, especially the ones targeting blogging, take a bunch of layout templates (e.g. site-header.html, sidebar.html, footer.html), your CSS stylesheets, your Javascript, and your posts (usually in markdown, but based on support you could probably use any syntax - markdown, yaml, plain html, razor) - and processes them to a colection of plain vanilla HTML/CSS/Javascript pages - one for each post. Each page generated is a complete and self-contained html page, combining all the common layout templates, the CSS, the Javascript and the Markdown content, with links between pages and navigation.

I picked Pretzel because it is written in C#. I know C# well so I can read the code, debug or enhance Pretzel if I ever so require. (Other possible options included Wyam, and Sandra.Snow).

Now Pretzel tries to keep as close as possible to Jekyll. Considering I am looking for a offline Jekyll replacement, Pretzel seemed appropriate.

And with Pretzel I can build/rebuild/run the entire site on my local machine with minimal fiddling (Which Jekyll setup, debug, or enhancement will all force me to do, and all in Ruby). As a .NET developer, my primary machine is usually all set to do just about anything with the CLR. Once testing is done, all I need to do is copy the local machine site folder into the folder from which Github serves project pages (the 'docs' folder under Github repository root). With build scripts, I can automate this step. When I check-in to Github, after allowing some time for Github to build the site and CDN propagation to happen, the latest content comes up on the public site.

For further details, check out the Pretzel wiki.

Setup

Setting up the repository in Github portal.

Do the following to setup your Github blogging. This method sets up a Project Site as the blog site.

And that's it. The blog post you are currently reading at https://insen.github.io/blog/ has been built in the same fashion, though we are still missing a few steps yet - We need to setup pretzel and then make our site look decent. But reversing th order makes things easier, So onto Hyde first, then Pretzel.

Importing Hyde to local machine.

Hyde is a pre-built theme for Jekyll. Since Pretzel closely follows Jekyll paradigms, It should work without issues, or so I thought. I was mostly correct. All we have to do here is git clone the Hyde repository at Github.

The reason we need this is that the basic site created by Pretzel is quite horrible, both aesthetically and structurally. I started looking for something that works from an aesthetic point of view, but as close to Jekyll as possible, which led me to Hyde.

Setting up Pretzel on local machine and basic usage.

Setting up Pretzel is quite straight forward. Get Pretzel from here, OR use Chocolatey - a package manager for windows. To use Chocolatey, install Chocolatey from here, and on an elevated command prompt or powershell console, run the command

	choco install pretzel

	pretzel create [options]

	pretzel bake 
		--source="c://srcpath" 
		--destination="d://dpath" 
		--cleantarget

	pretzel taste 
		--source="c://dpath" 
		--port=8001

Important note - the source directory in 'taste' command is the destination directory in 'bake' command. This is what we are using. For other options, check Pretzel wiki.

I will be creating batch scripts for the (bake) and (taste) snippets which will be useful.

Getting jiggy with it.

	Unhandled Exception: Pretzel.Logic.Exceptions.PageProcessingException: Failed to process E:\work\blogging\blog\_site\201
	2\02\07\example-content\index.html, see inner exception for more details ---> DotLiquid.Exceptions.SyntaxException: Unknown tag 'gist'
		at DotLiquid.Block.UnknownTag(String tag, String markup, List`1 tokens)
		at DotLiquid.Block.Parse(List`1 tokens)
		at DotLiquid.Document.Initialize(String tagName, String markup, List`1 tokens)
		at DotLiquid.Template.ParseInternal(String source)

Why? The reason here is that a sample post in the _posts folder contains, among other bits, the following content

{% gist 5555251 gist.md %}

And this does not work in Pretzel.

Why again? Because Hyde is a Jekyll theme, and Jekyll has a parser for the gist command. Pretzel does NOT. Delete this line from the post.

(However, this also means, you have to figure out an alternative way to embed gists in your post, if you need to).

My config.yml is shown.

# Dependencies
markdown:         redcarpet
highlighter:      pygments

# Permalinks
permalink:        pretty
relative_permalinks: true

# Setup
title:            'Some text'
tagline:          'Some text'  
description:      'Some text'
url:              'your blog url after publication - use https if https expected, else use http'
baseurl:          'your blog url after publication - use https if https expected, else use http. Could be same or different from previous'

author:
  name:           'a name'
  url:            'a url'

paginate:         5

# Custom vars
version:          1.0.0

connect:
  github:          '@github'
  linkedin:        '@linkedin'
  email:           '@email'

exclude:
  - docs\
  - .gitignore
  - .git
  - pbake.bat
  - ptaste.bat

Next is what?

There's quite a bit left to do -

But for now, this blog seems to be showing up on the internet. If you followed along this far with no problems, you should also be good to go.

Go forth, and typo. (pssst !! pun intended).

Additional resources

Related Posts