← Welcome to tl;dr
  Easter release
Fri 14th April 2017   
To celebrate the 20 years of Defence Force, I decided to make available the source code of my blog engine.

It's still missing quite a lot of things, the code is probably very n00bish here and there, but I've been using it for the last 5 years and I promised I would share it so let's be done with that!

Licensing

Before explaining anything, let's get the licensing part out of the box: If you don't want or can't use my licensing terms, there's no need to waste your time by forcing you to go through all that text!

I decided to go for the same one as I used for my Tilemap examples.


Copyright (c) 2012-2017 by Mickaël Pointier.
This work is made available under the terms of the
Creative Commons Attribution-ShareAlike 3.0 Unported license


The links gives details about what you can or cannot do, but basically the core of the idea is:

You can do more or less whatever you want with it, as long as you give appropriate credit1.

Presentation

I originally wrote this system because after a few years using WordPress I finally gave up with the never ending flow of critical updates, zero day exploits, broken plugins, spam, etc...

For the replacement what I wanted was the following:
  • No web interface to create the content: Less external access means less risks you get some intruder inside the system
  • Should support some form of macro language, while leaving me the possibility to directly hack some HTML or include whatever fancy javascript I want
  • Should require a minimum amount of additional software or server configuration
  • Should be as simple as possible to backup
  • Should be possible to forget about it without suddenly becoming a potential target for exploiters
Based on this, I looked around for what was available and either it was extremely complicated to use, required the installation of fancy frameworks and languages, or simply would not be flexible enough for what I wanted to do.

In the end I decided it would be a good learning opportunity if I tried to write my own system.

System requirements

The only thing you need is a web server with a working PHP interpreter, and eventually a Disqus account if you want to use the commenting system2.

Nothing is stored in a database, everything is just using simple files and does not require any particular access writes either: As long as php can access files in the folder where the blog is installed, it should all work.

Please note that the cross blog feature require a read access on all the sub folders of the various blogs (ie: They should probably be hosted on the same machine, or somewhat be available by a file share)

Features

The default feature set is relatively basic and basically matches what I needed when I worked on my various Defence Force blogs:
  • Automatic generation of a table of content
  • Automatic generation of links between previous and next articles
  • Support for multi-part articles with navigation bar in each article
  • Source code display with syntax high-lighting (using Google prettify)
  • Foot notes
  • Some basic picture framing
  • Some basic youtube embedding
  • Cross article references
  • Automatic tag cloud generation
  • Articles can have dedicated category icons
  • User controlled amount of text shown in article summaries
I may be missing a few things here and there, but the most important set of features are there.

Known issues

The whole system is not perfect, if you want something absolutely without glitches, or that would survive a slashdoting3, then please look away.

Some of the defects will probably be fixed over time, some will not be, but as of today, here is a list of what I know is totally crappy:
  • The CSS was built in totally haphazard way, it's not really "designed"
  • There's no What You See Is What You Get editor
  • The mix and match of HTML tags and macro commands may be confusing
  • If a line finishes by a HTML tag, there will be a missing carriage return (just add a space at the end of the line!)
  • The processing of the pages is going through multiple passes of search and replace, totally not elegant, and a waste of CPU power
  • The pictures are not optimized automatically, so if you embed a 5000x4000 pixels picture it will effectively be downloaded and scaled down by the browser
  • There is zero caching of the generated HTML code: Each time you click on a link the entire process of scanning the files and generating the content is done
  • The name of the articles is encoded in the filename, so the available character set is limited by the operating system
  • You have to edit the filename to edit meta information, that makes it no so source control friendly
  • The work in progress editing could do with more refinement
There are probably other issues, but it's all that comes to my mind at the moment.

Gallery

Nothing best to show what a system can do than to look at what was done with it.

So here is a number of my own blogs running on TLDR:

The 2D Game

The2DGame.com is a simple site with only a few articles.
I wanted to extend it, but I ran out of personal time, so it was not updated since 2012.

A good demonstration of the stability of the system: No maintenance required!

L3314N

L3314N.no is an offspring of the main Defence-Force blog.
There was more and more articles relative to the work done on our 4x4 military camper van, so I decided to migrate the files out and create a new dedicated site for it.

A good demonstration of the flexibility of the system: Just move the article files from a folder to another, no crazy scripts or indexing

OSDK

OSDK.org is an example of a more complex site which incorporates the blog like formatting engine into a more complex PHP site with custom code.


Oric 30 Yewars

Oric30Years is a slightly modified version of the system that uses two sets of articles, one for the English version of the site, one for the French version.
It also uses dynamically generated side columns to display a gallery of famous Oric software productions.


Blog

And finally Dbug's blog, the heaviest of all the Defence Force blogs so far.
It contains a significant amount of articles written since 2009 (some imported from the original WordPress site), but also features the cross-blog system which shows articles of the other blogs interleaved with the main articles of this blog: Each article has a custom CSS and logo depending of which blog it belongs to, and the cloud tag uses data from every article of every blog.


Future evolutions

I'm not sure yet what the future evolutions will be, but some of the most important things are probably to provide some form of picture optimization and content caching to limit the stress on the web server.

Considering the very organic way I'm developing this, and the fact I'm mostly doing it for me, don't really expect some nice and clean change history and version number and easy to merge releases.

Basically, the way it works is that when I'm writing new articles or working on my sites, I will find out that there is a need for this or that, and I will implement it. If it works nicely, I will propagate it to my other blogs, and at some point it will be available on TLDR with a new snapshot of the code

Anyway, feedback is welcome :)

Download and installation

What this downloadable archive contain is the entire TLDR site you are currently looking at.



tldr_1.zip


In theory you just need to unzip it somewhere, make sure that you can access it from php, and there you go.

If everything worked fine, you should have the following content on your drive:

TLDR archive content
TLDR archive content

Configuration

At this point, if you try to access index.php you should have the same site working.

If you don't, it means either there's a problem with the web server configuration, or you did something I did not plan and it broke horribly (in which case please contact me, it's probably something simple to fix).

Assuming it all works, your next step is to make it yours by doing some of the following things:
  • Edit setup.php
  • Edit the content of /css/user.css to change the appearance of the skin.
  • Replace /logos/logo_1.png by your own logo
  • Edit /pages/about.txt with your own content
  • Edit the content of the /articles folder
A this point you should still have the same basic structure as the original TLDR site, but with your own content.

Articles editing

Of course the crux of the thing is the creation and edition of articles.

Since you get the full source code of everything, it means you also got the source code of this exact article, so the best thing to do is to look at the content!

The first important parameters come from the encoding in the name of the files.

This particular file is named (right now):

2017-04-14$ART2$Easter release$easter$general,tutorial,installation,download,NOT_READY.txt

which can be decoded this way:
  • 2017-04-14: The date of the article is April 14th 2017
  • ART2: Unique ID of this article on this blog
  • Easter release: The name of the article
  • easter: The category of the article
  • general,tutorial,installation,download: Are four tags that will populate the tag cloud
  • NOT_READY: Is the magic editing word
The category is used to fetch one of the pictures in the /categories/ subfolder, so in this case it will use category_easter.png.

The magic editing word is the way work in progress files are handled.

Obviously when you create a new article you don't want everybody to be able to see it until it's ready.

The way this is handled at the moment is by inserting in the filename a string that matches the value of $GLOBALS['tldr_wip_keyword'] in the setup.php file.

For this file to appear in the list of articles on the blog, you need to specify the same magic work in the query.

I've left one such "work in progress" article on purpose, look at the difference between these two links
I admit that it's a bit crappy, but at least this way you can give the link to somebody else when you need proofreading without complicated mumbo-jumbo.

Macro commands

Basically the currently available set of commands is:

  • {title:caption}
  • {toc:title|floating}
  • {list:ul|type|somestring} xxx
  • {ul|type|somestring} ul/ol disc/square/circle
  • {source:cpp} xxx {cpp}
  • {youtube:video_id}
  • {picture:picture_name.png|caption|right}
  • {note:bla}
  • {article:reference|caption}
  • {multipart:Hack confessions|ART19|ART20|ART21}
  • {escape:somestring} xxxxx {somestring}
Note: I had to use the symbol { in place of the opening curly brace symbol because the parser is kind of primitive and interpreted the command list as actual commands.

So, if you look at this article, you will notice that I used the title command for each of my sections.

I also used the toc command to ask for a table of content to be displayed at the top right of the article (it uses the list of titles to populate it).

I've used the list command as well, but I have to admit that it does not really provide any advantage over the default html one

The note command was used here and there to add details at the bottom of the page4.

The picture command was used to display the folder content and can be clicked to open the picture in fullscreen in another tab.

The article command was used to link to the work in progress other article.

The multipart command was adds a box at the top and bottom of the article, with arrows to navigate between the various articles referenced as parameters.

And finally, the youtube command which was not used, so here is an example on how to use it:


I hope you will not find too many bugs, have fun!




4. Like that one that does not bring any useful information
comments powered by Disqus