Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
73 lines (45 sloc) 3.91 KB
title: How This Site Works (p. 1)
date: 2017-10-01 04:17 UTC
tags: meta, code
description: Learn about how the backend of this site was designed.
In this article I'll talk about my technical goals for this project and how it began.
For details about the visual design, check out <%= link_to('part 2', '/2017/10/12/how-this-site-works-p-2/') %>.
My goals on this project were as follows:
* Articles should a simple directory of Markdown files
* The site should be "static"
* Utilize an off-the-shelf tool so I don't need to start from scratch
### Goal 1: Markdown
I'm a big fan of [Markdown](, which provides a very simple syntax for creating formatted documents.
<%= marginnote("For example, " + link_to("the markdown for this article is available here", "")) %>
I feel like Markdown files are very readable and the syntax rarely gets in my way.
This way I can spend more time writing articles, and less time fighting with HTML.
Getting this to work was really easy, because almost every language has a good markdown parser.
<%= marginnote(link_to(tag(:img, src: ""), '', class: 'no-underline')) %>
You can view my articles (and even more nitty-gritty internals of this site) on my GitHub repo [here](
### Goal 2: Static Site
[Static sites]( are delivered to the user exactly as they are stored on the server, as opposed to a dynamic site which has pages that are generated on the fly.
After spending my career supporting dynamic sites (usually Rails), I wanted my personal site to be simple, lightweight, and inexpensive.
Ideally, this site would be a simple directory of HTML files that I could host anywhere.
<%= marginnote 'I opted to host this site on Amazon S3' %>
It's really easy to serve a website that's all static files, hell, I can even just email someone a zip of the directory and they'd have the whole site.
### Goal 3: An "Off the Shelf" solution
Since I didn't want to start this project from absolute scratch, I looked at a number of existing tools before deciding on a Ruby-based static site generator called [Middleman](
With Middleman I can still use code in my articles, but instead of that code running whenever a user visits my page, it runs only once ever: _only at the time I generate the HTML files that make up the site_.
I spent a few hours building up a "boilerplate" project that basically contains everything but the style and content of this site.
<%= marginnote '"Boilerplate" projects give developers a starting place if they wish to create their own' %>
I wanted to share it because if you know Ruby and want to run a static blog, this is a solid place to start.
You can view [my Middleman Boilerplate project]( here.
It's intended to be a comfortable starting point for creating a new website if someone wishes to in the future.
The process of writing an article is running `middleman article`, which generates blank article for me to add content.
To make my life easier, I can run `middleman server`, which launches a development server, allowing me to make changes to the article and view them in my browser in real-time.
When I'm content with the way the article looks, I run `middleman build` and the article will be compiled to HTML for uploading to S3 for the world to see.
For example, <%= link_to "the source code for this article is available for you to check out here", "" %>.
In <%= link_to('part 2', '/2017/10/12/how-this-site-works-p-2/') %>, I talk about the visual design of the site and how I did it.