Introducing Glyph: Static Site Generator Powered by Github Issues and Pages

[dbriemann]

Another blog and another static site generator? In 2018? I know what you think but please read a few lines first if you made it this far. This one is a little different from previous static site generators.. I promise! Oh and by the way, you are just reading a Github issue!

First of all, the best time to start a blog must be when you release a static site generator.. so hey.. hello world! I will be writing occasionally about coding topics that I deem interesting and especially about making indie games as a solo-dev. As you might have realized this time it is not about games.. so what is it all about?

Glyph & Glyph-Zero

I just released the beta of glyph. It utilizes the great ecosystem of Github Pages and Github issues to author, export and host a static site. Tightly coupled with it is glyph-zero which is the origin template for all glyph powered sites.

• Glyph is the command that generates a static site from a glyph-zero template.
• Glyph-zero is a template, ready to be forked, that includes all configs and themes needed for a glyph powered blog.

Motivation

I got inspired by this blog which is entirely hosted on Github issues. At first I was a little confused because that is not the typical use case for issues. However there are clear benefits to it:

1. You have a great comment system just available without doing any extra work or creating new accounts.
2. You can write your blog posts in markdown which is simple and offers enough styling for a blog.
3. You can write the markdown directly in your browser in Github's great markdown editor, with live preview.
4. You can mention people on Github in the issues(posts) and the comments.

After presenting you the benefits there are also some drawbacks:

1. You cannot change your blog's style. Github issues doesn't look too bad but maybe you don't like it or want a personal touch.
2. You cannot track people with Google Analytics or use other scripts. I personally am not a big fan of this in the context of a blog but the option is somehow important for people.
3. You cannot fork the issues and thereby create a backup of the content. A blog hosted on Github pages offers this option.
4. You cannot use a feed reader to follow one single repository and the attached issues (not 100% sure about this).

How it works

Glyph removes all of those drawbacks for you. It renders all of your open issues from one repository (your blog/site) to HTML and places them in your docs/ folder inside the repository. You then commit and push them all to Github and voila.. your site is published on Github pages with a custom theme and the content extracted from your issues. In addition an Atom feed file is generated and a link is ready to take the viewer to the comments section (on Github) of the issue for discussions. All links that point to other issues of the same repository are converted to links inside the blog, e.g. https://github.com/dbriemann/blog/issues/1 is now an internal link.

While glyph aims to be as simple as possible it allows you to fully customize your styling and scripts. glyph uses the mustache templating system. The default theme is used on this very blog. I'm not a designer but I gave my best here. If you make a new theme or improve upon the default theme please contact me or send a pull request on Github!

All instructions on how to use glyph can be found in the glyph-zero readme. It is a very simple and straight process so give it a try!

What's Next?

• First I want to add syntax coloring for markdown code blocks. This will probably be a rather simple addition to glyph and an option in the config file.
• A bigger thing will be the integration of Github comments into the generated site. My current idea is a (java)script that fetches all comments from Github and displays them on the site. The benefit of this is obviously that we have the same theme/style for comments and content. However I will need to ponder on this for a little longer.
• Another big one is supporting Travis on glyph-zero. The ideal scenario would be that Travis auto builds the blog as soon as an issue is created or updated and pushes the generated files into the repo. I am not sure if that works but I will investigate sooner or later. If this works we don't need to do anything on a local machine. The repo can be forked, the config files can be edited on Github and then it would just be about creating and maintaining content within the Github ecosystem.
• I may add support for Github Access Tokens again. I removed that feature in the beginning to keep everything simple but maybe it will be needed for future features. Currently you don't need a token because Github allows 60 API queries each hour from an unauthed source.

I am also open to ideas/improvements from you readers. Contribution of any kind is very welcome. Just keep in mind that glyph intends to stay easy for the user. Currently the glyph command has no options at all and I like it that way.

[breml]

@dbriemann Interesting idea, especially if combined with travisci. The problem I see is, that there is no way on GitHub to prevent other users from creating issues. Is there a way in glyph to only convert issues from a particular user to blog posts?

[dbriemann]

@breml There already is a solution in place for this problem. The main config.toml has a Users array that specifies which Github users are allowed to create Issues in the blog (other users can create issues too but they won't be rendered to html pages). Because of this it is also easy to do collaborations with Glyph.

The first user in this array always needs to be the repo owner (in this case it's my username dbriemann).

[breml]

@dbriemann Very nice. Instead of travisci one could also use AWS Lambdas for the automated updating of the blog. See https://aws.amazon.com/de/blogs/compute/dynamic-github-actions-with-aws-lambda/ This lambda could also do other stuff like closing issues from not allowed users.

[dbriemann]

@breml That looks intresting! It also told me about Github Webhooks which I wasn't aware of.. I will certainly have a look at all of this and take it into consideration for the automatic building feature of Glyph.

[craigmulligan]

Super interesting idea @dbreimann. Would be cool to make use of issues tags and correlate them with Jekyll tags. Or simply uses them to mark issues as drafts/published.

[dbriemann]

@hobochild check glyph's issues. I think I have the draft idea covered. I will also add a feature issue for some tag management. I already had it in mind but forgot to write it down.

What exactly do you mean with correlating tags with Jekyll tags?