First full post in markdown!


Written by Admin

As part of the massive overhaul we recently underwent, one of the biggest changes was switching from a mostly static PHP site, to a fully static HTML site. My main reason for this was simply speed and simplicity. I don’t love dealing with PHP. It serves a purpose, but more times than not, a page would end up being 95% HTML and 5% PHP. So it ends up just being wasteful. As I was doing this, the thought occurred to me that I didn’t want the blog being a separate entity anymore. The last site redesign we did, I hacked together a basic header and footer, and called it a day. The sites were never really integrated other than a link from the main site to the blog, and the fact that my lazy header basically forced you back to the main site, because there were no real links to other WordPress pages. At first I was going to attempt to make a full theme for WP to match the site. I got about an hour into it, and things were looking good. That is until I got to my massive menu. Trying to rebuild that in WP would’ve been a nightmare. I gave it about 5 minutes of my time before deciding aw hell nah! I was completely done with the bloat and constant updates required with WordPress anyway, so I decided to figure out a way to do the blog in pure HTML, and make it part of the main site. After looking at a few other Static Site Generators, I found Jekyll. While somewhat dated, it’s still a powerful SSG that fit my needs, and excited my inner geek.

As I had already completely built the rest of the site, and had also started used Gulp to manage my build flow, I had to decide how to handle it all together. I decided to just get started on the basics and come back to the full build flow later. Since I already had a full build basically waiting to be published, I just sucked all the pages and CSS into my Jekyll development environment, giving me my full site to work with. It was super easy to get started taking advantage of some of the great features. One of the annoying parts about static HTML, is you can just include a header/footer on a page, without doing some sort of server side code to make it happen. That means on a site with 20+ pages, every little change has to be made that many times. A lot of it could be done via mass find/replace in VS Code, but it gets kinds sketchy doing that. So one of the very first things I did was take advantage of the _includes in Jekyll. It’s as simple as creating an HTML file under that directory, for example header.html, dropping your snippet of code in, then including it on another page with {% include header.html %}. 💥 270 less lines of code on every page! 💥 Same thing with the footer.

Next I decided to make a default layout for the bulk of the pages. This consists of rest of the shared static content from the opening <html> tag to just before the <head> starts (which is in the header.html), then the remaining code from right after the </footer> tag (which is in footer.html). Then I just pop the includes in for the header and footer, and thrown another special content tag, which will inject the content of an html page into the layout template, to render the full page. layout code looks something like this:

<!DOCTYPE html>
<html lang="en">
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <!--favicon icon-->
    <link rel="icon" href="https://cdn.serve-you.net/assets/img/favicon.png" type="image/png" sizes="16x16" />
    <!--title-->
    <title>{{ page.title }} | {{ site.title }}</title>
    <link rel="stylesheet" href="https://cdn.serve-you.net/assets/css/main.min.css">
</head>
<body>

{% include header.html %}
    {{ content }}
{% include footer.html %}

</body>
</html>

Once that’s in place, the code on each page needs to reference this layout. This is done through something called Front Matter. Front matter is basically a set of variables that control how a page is to be processed. On a normal page on the site, this is usually just the title and layout. for example:

---
title: Home
layout: default
---

This tells Jekyll to overwrite the page title, and use the default layout page. All that’s left is the actual unique content for that page. This makes it so much quicker to do things, as you basically have a template in place for every page. I wish I had found Jekyll before I had basically finished the damn site!

Now that I had all of my pages broken up in a much easier to maintain flow, I finally got started on the blog portion of the site. You would not believe how simple the migration from WordPress is. Now, obviously I did not have a ton of content to deal with, so take this with a grain of salt. It took me all of about a minute to export the posts from WordPress using the WordPress Export tool in the admin panel. It dumps them into an XML file, that you then import into Jekyll with one of the many plugins for this. I chose the awesome ExitWP python script, and it worked like a champ. Within a couple of minutes I had all my posts converted to single page markdown files, complete with tags, categories, titles, slugs, etc as front matter. There were a handful of tiny edits I had to make for images and such, but otherwise, it was smooth sailing.

To integrate it into the site, I decided I wanted a single page as an entry point, which displays a list of posts in snippets, then link to each individual post page. Simple! They already have builtin methods to do this, or of course there are plugins to do it a different way. In order to keep things in check since this site is not a blog first site, I wanted to keep all the blog stuff under it’s own realm. So I wanted to have it all live under /blog/ using permalinks, but not affect the rest of the site which should operate as normal. To do this, I set the permalinks to /blog/:year/:month/:day/:title in the config file, and on the blog.html page, I gave it it’s own permalink of /blog/. Luckily, normal HTML pages are ignored, so only the posts follow the permalinks. This allows everything on the blog page to stay within /blog, basically making it have it’s own root. By setting all of the menu navigation links to relative to the root directory, all of the normal navigation still works as expected.

From there I just had to make some simple navigation within the posts, which was a few simple lines of code. I still have a few things I’d like to do, but it’s functional, and doesn’t look terrible, so I’m content for now. When I get some time, I’m going to make a sidebar nav for the blog pages, and I need to figure out the pagination stuff, since my blog page is actually displaying all posts, instead of the handful it’s supposed to. Aside from that, I have to work out my real deployment workflow, since I completely broke it. Right now, I’m just manually processing tasks in Gulp when I need something, and then I just run the Jekyll build to create all the finished files. Then I push them to git, and I have a post-receive hook in my repo on the server that just does a git checkout on the branch. Eventually I’ll tie all of this up in a github action or something, but that has to wait till I have some more time to commit.