Introducing Glyph: Static Site Generator Powered by Github Issues and Pages
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:
- You have a great comment system just available without doing any extra work or creating new accounts.
- You can write your blog posts in markdown which is simple and offers enough styling for a blog.
- You can write the markdown directly in your browser in Github's great markdown editor, with live preview.
- You can mention people on Github in the issues(posts) and the comments.
After presenting you the benefits there are also some drawbacks:
- 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.
- 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.
- You cannot fork the issues and thereby create a backup of the content. A blog hosted on Github pages offers this option.
- 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.