blog

Simple personal blog framework

This is repository serves a two-fold purpose: firstly, as my personal blog generator and framework; and, secondly, as my blog itself. These goals are, at the same time, both necessarily interlinked and completely separate.

In one hand, this is a framework. It has scripts for page generation, its highly opionated on its syntax and has tools for actually serving the pages themselves. On the other, its a collection of pages on a variety of topics of my own personal interest, written within this framework. These pages serve as both testing input for the framework and as the blog itself when generated.

The result is an hybrid of a blog focused framework and of the personal blog itself. A chimera of tools and content both personal and general. The programs might help you create a site just like mine, but, even better, might set you on your way to create it whitin your own conceptions of what is good design. Beyond it even, might propel you forward on writing your own programs for personal use, giving birth to a chimera that is at the same time different and perfectly alike mine.

The framework

The framework touches on three major parts:

1. Writing the pages. Which on touch the macros, the HTML style and the directory structure
2. Generating the site, done via build scripts
3. The web server. Which serves the site proper.

We will go through these in order.

Writing the pages

The process of writing the pages involves three steps: application of proper HTML writing style, the macros in use and the type of the page. None of them are particular complex steps.

Conventions of writing

Firstly, while there is some quality of life features implemented via M4 macros or directly in the generation script, the bulk of the web page remains normal HTML, albeit in its shortform, that is, HTML that takes advantage of optional tags and proper indentation.

The common practice of being verbose when writing HTML tags, while normally correct for most enviroments, is simply inappropriate for the common writer. Much better is, instead, to write HTML with a syntax that more closely resembles Roff programs, which is one that mostly eschews indendation and describes the formatting on the beginning of the previous line. For example:

<title>A simple HTML page</title>
<h1>A simple HTML page</h1>

<p>
A brief paragraph, describing something of great importance.

<p>
Here is a list for you:

<ul>
<li>First item.
<li>Second item.
</ul>

This is far simpler and more digestible than being fully verbose. We can go further and omit the title tag, since it would be generated by our build script from the h1 tag. This is done because all pages usually have only a single level heading anyway.

Directory structure

Now, the placement of the files vary according to their type. There are three types of files in the site's directory structure: pages, posts and parts files.

Pages (pages.html) files compose files that are their own thing. Usually a about page or the site map. Posts (post.html) refer to the blog posts, which usually fall within some category and, lastly, the parts (part.html) are files that are included, via the M4 include macro, in other files.

Macros

Currently supported, is the hability of having a link array for all the links in your pages. For example, if you add the following line to the macro file:

links.push(`my_page', `www.mypage.com')

You can later reference the link using links.fetch:

<a href="links.fetch(my_page)">video</a>.

This is added both for the convenience factor, but also it makes reading and editing the source code of pages more confortable.

Another simple convenience feature is the <todo> element, which gets expanded to a paragraph of class="todo" for which is styled via CSS.

<todo>
A todo paragraph

Lastly, and perhaps the most useful of the macros, is the include macro. For example:

include(page.html)

Will include a file named page.html at whatever part this file is named.

For now, syntactically, these are the only features supported, but probably more will come in due time.

Why not markdown?

A probably common question being leveraged right now is: why not just use Markdown?

Its a question not without merit. After all, Markdown is a well established format, praised by writer and developer alike. There is night textbox in in the web that doesn't support at least a subset of it. Hell, even this README is being written in Markdown. Why, then, not just bite the bullet and use it?

Well there are a few reasons.

For starters, Markdown syntax is one deceptfully simple. While it prouds itself in being source readable code, findings its origins in the conventions adopted in the USENET of old, Markdown simply its not enough for the use cases the go beyond that of its roots. Its a language born out of forum posts, which require only a subset of features from most markup languages, basically: headings, bullet lists (numbered or unumbered), emphasis and quoting.

This particular set can cover most users needs of expressing. A great amount of texts, both ancient and modern, won't need much more than that. But many texts will end up requiring, especially those developed by programmer's. Its of no surprise that amount of Markdown extensions, flavors and even conventions that one can find, each of them offering an alternative or a solution to some common problem that Markdown is simply not cabaple to handle. What is often forgotten is that its incapability does not stem from oversight or error, but from its very design. Markdown mimics the etiquette of online forums and it excels in this particular use case, but anything past this requires a great deal more of work, usually calling for more extensions or the behaviours of a specific compilers. The saving grace of Markdown, and probably the reason why it has stuck around for so long, is due to the recurrence of this basic case. The bulk of most of written text will be just what it offers: headings, quotes, emphasis and bullet lists. Most of the of what I write fall within this category, the issue arises whenever I want to do something more. The usual answer to this is: Markdown is merely a superset of HTML, at any given moment you can drop back to it. This response has its shade shade of truth, but is not without its flaws.

In my view, Markdown greatest strength lies in its ease of use. Its simple to write and to read it, there is probably no other markup that can be truly considered source readable. But as features and further structures are superimposed on its uncomplicated core, more and more it resembles most markup around. If I have to drop down to HTML recurrently to do what I want, or have to cave to various Markdown implementations and extensions, for one, I'm not using Markdown anymore; and, for other, I rather not use Markdown anymore. In this scenario, the source has become as readable and as editable as any other markup language, but now with twice the hassle of setting it up. In this situation, I see no reason to not just using HTML while taking advantages of its optional tags and avoiding indentation whenever possible. The end result is a slightly more verbose Markdown with none of its drawbacks, plus with a removal of all the convertion infrastructure.

Unfortunately, whether we like it or not, the marked up source of our documents can only be as readable as the use case demands it. If there are certain markup languages considered more or less source readable than others, it usually falls down to a matter of taste, assuming they have support for equal things. Markdown was especial that it stood alone as the actually source readable markup because it barely even looked like markup, its simplicity even evident by the layman's adoption of it. This was the my initial reason for using it, I could read both the source as the generated document. Alas, two things eventually became clear for me: first, no matter how readable the source, nothing beats the formatted document; second, Markdown, when coerced for the uses of the programmer and not the forum contributor, becames akin to HTML, but with parts clearly forcefully bolted on top.

That all said, I still think Markdown has its place and value, especially where it has been culturally become the norm (forum posts, project's READMEs). The reasoning presented here is merely to justify my preference for this framework and for my own posts going forward, since I had initially attempted to utilize Markdown for this purpose, but wasn't satisfied with the result.

Generating and serving the site

To build the site as its stands, merely run make at the project's root. To run it, just type make run.

The build script will generate the appropriate site with metadata and properly nested table of contents for each of the posts.

For the particular case of a page named index.page.html, the script will create a site map mimicking the structure of the posts directory. You can customize the domain name and port number by passing the DOMAIN and PORT variables to make.

Considerations for general use

This is still a work in progress and, as it stands, it clearly has a lot of its parts hardcoded for my own use. And, while I do believe into exposing more functionality for general use, I find it hard to disassociate this project from my own strange and evolving human idiosyncracies. I rather that you, potential user, see this hybrid framework-blog as it is and going forward, mostly as a blueprint or as a source of inspiration.

While there is complexity here, its far simpler than what, as far as I know, is usually peddled my the web frameworks. It can be build and maintained by a single individual, because it doesn't have a lot of moving parts. It only parses pages, adds stuff to them and serves them. It leverages robust techonlogies that have been around for a while. Truly, its only as complex as it is due to the fun I have building it. One could completely remove the build script and simply add what it does by hand. Through the magic of copy and pasting and templates, very little time would be truly wasted in comparison to writing it, maintaning, etc.

Ultimately, the tools here don't aspire to be general, to be the best in the market, to overtake whatever already exists and so on and so forth. They are just what they appear to be: a passion project from someone throughly interested not only in writing, but on learning and building the tools that surround the writing process.