Homely

Homely is a web content management system (CMS) that I built to power my own personal website. I had been using WordPress, which is a wonderful CMS, but I decided that I really wanted to get back to a website powered by my own code.

Back to Basics

I built this new site and CMS with a focus on stripping things back to their most basic form.

• Generate small, lightweight pages - The site shouldn't ask much of visitors' browsers.
• No unnecessary tracking - I'm not selling ads here so I don't even really need analytics.
• No Database - The site is so small I can easily accomplish the same by using static files.
• No Web Interface - I may still change this, but this means fewer vulnerabilities for hackers.
• No HTML Editing - HTML is just a royal pain in the neck to edit as code, but I also wanted to avoid relying on a WYSIWYG editor.

Enter Markdown

Markdown (as opposed to markup - get it?) is a very simple text-based format that can be transformed directly into HTML. It gives you a lot of the most important HTML objects but without the need to wrangle a million angle brackets.

If you'd like to learn more about Markdown, check out markdowntutorial.com.

In this website, I create pages as Markdown files and upload them directly through SFTP. There's no need for any specialized editing software, nor for a web-based editor interface.

I did have to make a slight modification to my files, however, since there's no database. The first 3 lines of the markdown file contain metadata used in building the page.

1. The page title
2. A URL for a thumbnail image (optional)
3. A description of the page (optional)

The title of course gets populated into the <title> element when the HTML page gets built. The thumbnail URL and description are used to provide metadata for Facebook and Twitter so that my pages can have nice previews.

After getting that information, I throw the remaining text into a PHP Markdown parser called Parsedown to get the main text of the page.

URL Trickery

One neat trick I picked up from WordPress is how it handles URLs. WordPress actually relies on the web server to do a URL check first. If the underlying server sees that the file requested exists, it just serves that file directly. Everything else it passes to /index.php where WordPress can see what you requested from the $_SERVER variable.

Homely does the same thing (in fact I just outright copied the WordPress .htaccess file) but everything is handled in a much spedier way and without the need for a database.

First, it takes the URL (ex: http://mattpierce.info/homely), cuts off the beginning (ex: /homely) and converts that to two file names (ex: /pages/homely.md and /html-cache/homely.html).

If the Markdown file doesn't exist, it will:

• delete the HTML file if necessary
• display a "file not found" message

If the HTML file doesn't exist, it will:

• generate a new HTML page from the Markdown file
• display the new page content

Now here's where it gets a little tricky - if both files exist, the system needs to figure out if the HTML file should be updated. There are two things that can cause an update:

1. If the Markdown file is newer than the HTML file
2. If the Template file is newer than the HTML file

By using the timetamps, Homely is able to cache output to minimize server load and also ensure that the cache is always up-to-date.

A Few More Tricks

As you've probably gathered by now, the system also relies on a template file (always located at /template/template.php). This creates the page surrounding the body copy (the header, footer, etc).

The system also relies on a settings file that holds a few variables the template can use to build the site, like a site-wide title and a twitter username to use when generating metadata.

Downloading and Installing

Download Homely (ZIP)

To install, extract the zip file into the root directory of your website. Once extracted you should be able to view a sample homepage. From there, you can immediately start making new Markdown files or start building your template.

Note: For Homely's cache to work correctly, you need to make sure that your web server can write to the /html-cache/ directory. If you forget this step, the website should still run - but it'll run more quickly and use fewer resources with a cache.