Uberlight: Minimalistic Flat-file Blog Engine Written in PHP
Uberlight is fork of a minimalistic flat-file blog engine written in PHP called hyperlight, which you can find on GitHub. My desire for my own blog was to even have a more minimalistic engine, so I forked hyperlight and stripped down some of the features, changed others and added more to suit my needs. Although the theme can be easily changed, my particular taste favors a simple style as you can see here. But even after stripping down hyperlight to a certain extent, there were features I wanted to add. So in this post, I describe some of the new features and how to use them. Firstly though, I will briefly describe how posts are written in uberlight, preserved exactly from hyerlight.
Uberlight has a config file which specifies a 'posts' directory. To write a post, a Markdown file is added to the posts directory with the extension '.md'. The prefix (i.e. the string preceding the extension and referred to in hyperlight as 'slug') is the unique label that is used to locate the post. The file starts with the title of the post. The next line is a description of the post. Another line below describes a series of optional tags, separated by commas, which are only used internally in uberlight, which differs significantly from their purpose in hyperlight. The body of the post file is written in Markdown and provides the content of the post. One feature I have added is a way to obtain the raw content of the post in Markdown, so a link is given at the end of every post which does exactly that. You can find it at the end of this post and inspect the raw Markdown form if you so wish.
Now we turn to the main new features I have added in uberlight, which accomplishes things that I would personally like to do in my own posts.
Math Expressions in TeX
We would like to write math expressions in TeX. I use the MathJax Javascript library to render mathematical notation written in TeX for display in the browser. So to write a TeX math expression inline in the markdown file, we use backticks to enclose it in a code block, and then within the backticks we write the TeX expression using the usual delimiter, namely a $ symbol. For example, consider the following sentence.
Let $n \in \mathbb{Z}^+$ be a positive integer.
Now the markdown to produce the above is:
Let `$n \in \mathbb{Z}^+$` be a positive integer.However there is still some work to do. The code blocks within the produced HTML mean that MathJax will ignore the TeX. Furthermore, the dollar sign delimiters need to be changed to \ ( and \ ). Note there is actually no space between the backslash and the parenthesis but here we need top stop MathJax processing the text. Luckily, without having to reinvent the wheel, Yihui Xie solved this problem in his blog post here with a piece of Javascript that preprocesses the code tags, changes the delimiters for the TeX expressions and then removes the code tags. So I use his code in uberlight, and you can find it here. With this script added, we can comfortably use TeX expressions in our Markdown file, like we have done above.
Updates
One feature I wanted to add was a means to extend existing blog posts with updates, which can be added over time and appear at the end of the post. The way I accomplish this in uberlight is with additional files in the posts directory with specific names. Suppose you have post labeled 'example' such that there is a Markdown file in the posts directory with the name example.md. Now suppose we wish to add an update to such a post. To do this, we add a file whose name is the label of the post (in this case, 'example') followed by a hash symbol and an arbitrary string (which might describe the particular update) - then naturally the '.md' extension. This file has the same form as a post and the content is written in Markdown. An update will then be added to the post. The updates are ordered by modification date of the files, starting with the oldest towards the most recent. To illustrate this, I have added an update to this post by writing a file called 'uberlight#1.md' to the posts directory and you can see the result below at the end of the main post.
Extended Markdown
One of the motivations for developing an extension to Markdown was a desire to have a way to automatically and easily add theorems and proofs that are styled in a similar manner to LateX. Such 'environments' are not supported by MathJax, which only deals with math expressions. Furthermore, I thought it would be nice for the theorems etc. to be numbered automatically with an easy way to reference them throughout a post. For my extension to Markdown, read my post describing it here.
Note as of writing, I have not as yet put the code on GitHub. I will do this very soon and add an update to this post to say that it has been made available.