Author: Ipstenu (Mika Epstein)

Mailbag: Why Jekyll?

Why didn’t you convert your site to WordPress? You said you had to import it from Mediawiki to WordPress already.

I had this conversation with my wife, too.

WordPress is awesome at being a dynamic website. To be a static ‘wiki’ style website, it sucks. It’s not meant to be static like that. It’s not intended to be static. Even if you turn off comments on your site, you mean for WordPress to generate index pages and categories and the like.

With WordPress, all that work is done on the server. When you visit a page, it’s generated for the first time. I may have a cache that lets reader number 2 see that page, but always the page, the HTML, is being dynamically built on-demand. MediaWiki works the same way. In contrast, Jekyll is dynamically built on my laptop and deployed as an in-situ static site. Each HTML page is a real HTML page on the server. No extra work has to happen. It’s small, it’s light, and it’s fast, because all that processing was done by me on my laptop before putting it on the server.

And that actually illustrates the problem with WordPress, and why we struggle with things like Varnish and nginx and caching. We want our sites to do more and be faster. We need flexibility and posting to Twitter and dynamic page generation when we make an edit, because we’re constantly making changes.

Except I didn’t. I don’t. Not the particular site I was working on, anyway. The site has about 1000 pages (probably closer to 600 once I decided not to import some of the things) and they’re pretty static. At most I updated them once a week for half the year. WordPress would be overkill. Hell, the Wiki was overkill and the only reason I kept using it was technological debt. I didn’t want to add to the debt. I didn’t want to make things even weirder and harder to use. I didn’t want to put a site more at risk with software I didn’t want to upkeep (MediaWiki, not WordPress).

So it was clearly time to dig myself out with a little sweat equity and decide what I really wanted. I made a list of what I needed, what I wanted, and what I could live without. When I did that, Jekyll started looking more and more like a viable option. I would have spent as much time removing the aspects of WordPress I don’t need as I would have learning a new theme system and language.

Also in the end I didn’t use the WordPress import. I manually copy/pasted content. The content was what I wanted, and I needed it text only, and MediaWiki made that damn hard to get at. Of course the Jekyll exporter for WordPress was pretty freaking cool. If I was pure WordPress to Jekyll, I’d be fine. I guess there just aren’t a lot of people doing MediaWiki exports.

23 October, 2015
Jekyll Collections
Early on, Jekyll’s developers said that if someone was using posts for non-blog content, they were doing something wrong. That left one other avenue open, the first time I looked at Jekyll, which was pages. They’re nice, but they’re not what I wanted.

Enter Jekyll collections. These are ‘arbitrary’ groups of related content which you put in their own folder. I had 15 years of interviews collected, so for me this seemed like a perfect idea. I read up on Ben Balter’s – Explain Jekyll Collections like I’m 5 and it helped me sort out what I wanted.

Configure

This is easy. You just add the collection code to _config.yaml
```
# Collections
collections:
  interviews:
    output: true
```
Having the output set to true means that when I run jekyll build the pages are generated. That’s pretty simple. They don’t get auto-generated when you run a jekyll serve and you’re testing locally, however. Which sucks. I upgraded to Jekyll 3.0 beta and it started working, though, and I’m okay with running a beta.

Create A Folder

Also easy. Make a folder called _interviews in the main Jekyll folder. I will note, this gave me a fit. I wish I could put all my collections in a subfolder, because now I have this:
```
_data
_includes
_interviews
_layouts
_pages
_posts
_sass
_site
```
It’s messy, and if I didn’t know that some of those folders are special (like _includes) I could easily be confused. The _site folder makes some sense, that’s where my site is output. But even if I use the source setting to move all my source pages into a folder (called _source in my case), I still can’t separate the code from the content. What I would like is this:

_assets – Store all of my ‘code’ like layouts, plugins, css, etc here.
_content – Store all my post content, collections, pages, etc here.

Still this is a little better for me. Less insane. I will note, I was able to move my folders by defining the directories in my configuration file like this:
```
# Moving Folders
source:       _content
plugins_dir:  _jekyll/plugins
layouts_dir:  _jekyll/layouts
includes_dir: _jekyll/includes
```
So now my main folder has two folders _site and _content which is a lot easier for me to work with. I feel less muddled. Inside the content folder is a _jekyll folder which is my ‘wp-content’ folder, and a _data folder, which has some data files. More on that later.

NB: This only works on Jekyll 3.0 and up!

Create Files

All I had to do was make my files in my _interviews folder and I was done. Well. Not really. I needed a way for Jekyll to link through everything, and I really didn’t think making manual pages was smart. I tossed in this code to my interviews post file and it cleverly looped through everything it found, generating the page on the fly:
```
<ul>
{% for topic in site.interviews %}
	<li><a href="{{ site.baseurl }}{{ topic.url }}">{{ topic.title }}</a></li>
{% endfor %}
</ul>
```
If you’re familiar with WordPress loops, this is the same thing as saying “For all posts in a category…”

Customize the Hell Out of It

Of course you know that’s what I did next. I went and made it super-complex by putting my interviews in year subfolders and then making the main interview page a list of all the years, with links to those pages, and loops back and … well. That’s another post.
21 October, 2015
Bye Wiki, Hello Jekyll
I’m trying to make life less messy by learning an entirely new system.

I have a Wiki with 1000 or so pages and it’s running MediaWiki. And it’s overkill. I don’t update it often enough to need all the bells and whistles. I need it to be fast, I need it to be simple. I need it to work for one editor (hi). Oh and I need it to be secure.

Create a Git Repository

There’s a reason for this. My plan is to commit my changes for Jekyll to a git repo and then have it auto-copy the proper files up to the folder on my webserver. My git repository is private and on the same server owned by the same account, so I can do this. Once I had my bare git repo, I ran this in my local repository folder on my laptop:
```
git clone ipstenu@example.com:/home/ipstenu/repositories/jekyll.git site-jekyll
```
And I got a warning: warning: You appear to have cloned an empty repository.

Which I knew. But that’s fine. I wanted it empty.

Install Jekyll On Your Computer

Full stop. This is where I got confused before.
```
$ brew install ruby
$ gem install jekyll
```
That’s it. That’s how to get it started.

Create Your Site

I was still in that other folder, so I ran an install:
```
jekyll new . --force
```
The reason for the force was that I did have some git files in there and a readme. Then I spent a few hours trying to figure out how to write posts and pages in Jekyll. Posts are ‘easy’ in that you create a file named yyyy-mm-dd-PostName.md and it will generate a post with that name. You can read up on Writing Posts for more.

But. I’m converting a Wiki and pretty much the whole thing is going to be ‘pages’. To be honest, Jekyll’s idea of pages are ugly. The Writing Pages directions want me to put it all in the same folder and I didn’t like that. I thought I’d rather write a mess of posts in the _posts folder and then let Jekyll generate on the fly.

To do that was relatively easy. I set up permalinks:
```
# Outputting
permalink: "/:title"
```
After I did that, I realized I would still have to name things that ugly way, so I added this to my _config.yaml file:
```
# Pages
include: ['_pages']
```
Then I made a folder called _pages and put my files in there, named CSI_Crime_Scene_Investigation_(season_1).html and so on, with headers like this:
```
---
layout: default
title:  "CSI: Crime Scene Investigation (season 1)"
permalink: "/CSI_Crime_Scene_Investigation_(season_1)/"
categories: television
tags: csi
---
```
Yeah. It’s starting to make sense. I could change the permalink to ":/title/" and get the same result, where it would match the filename. But for now, the basic idea is enough.

Themeing

It was harder than expected. I had to convert a lot of random PHP includes into Jekyll includes (pity I can’t just say ‘include this file, yes, I know it’s PHP…). Then I wanted to add some features like a table of contents, like I had from MediaWiki, which was a little tricky. But. Once I sorted out the way you do includes and how I could do them, it was all a bit easier.

Importing MediaWiki

This proved to be incredibly hard. Like table flipping, teeth gnashing, up at night, wondering why the universe was created this way hard. It was so hard, I exported the wiki to XML (easy), converted that to WordPress xml via Perl (hard because of dependancies), edit all instances of <wp:post_type>wiki</wp:post_type> to be a post, import into a WordPress site (easy), and then …

Then I spent a long time going through the import, fixing the pages, formatting things, uploading images properly, etc. The wiki I was importing was old. It happens to be the oldest part of the website it’s on, and I was using a lot of templates. In a way that was great. But in another way it was really a terrible idea because it locked me in.

So a lot of things had to happen. First, I had to rebuild all my templates. The wonderful thing with this is that I was using a lot of templates to list things like episodes and I could convert those to yml (or csv) and then have Jekyll run a loop to display them. Once I realized that, it meant I had a lot more freedom with content.

I ended up not importing everything. A lot of what was on that Wiki was never looked at by anyone but me, and fifteen plus years of cruft leads to a lot of messy things. Between Jekyll collections and data, I was able to break things out into sanity again. But that’s a whole post on it’s own.

Pushing To My Server

I’m using Git, and it’s set to auto-push when I push. But this time I did it a little different. Normally I’d run jekyll on the server, but in this case I don’t have the option so I went with adding my _site folder to the git repo (which meant editing .gitignore) and then writing this:
```
#!/bin/bash -l
GIT_REPO=$HOME/repositories/jekyll.git
TMP_GIT_CLONE=$HOME/tmp/git/repositories
PUBLIC_WWW=$HOME/www/jekyll

git clone $GIT_REPO $TMP_GIT_CLONE
cp -r $TMP_GIT_CLONE/_site/* $PUBLIC_WWW
rm -Rf $TMP_GIT_CLONE
exit
```
This is not what I would consider a great idea. I’d rather run git on the box, but Ruby has been misbehaving there, and this actually lets me use the code on a shared box too.
19 October, 2015
Mailbag: Delete My Account, Please

Becuase I’m active in the support forums, people find me and ask all sorts of questions. Like Charlie.

I want to totally delete my word press account. I will PAY you to do this. Why? Because I worked for 15 minutes on the original word press website but found it too difficult for me and chose to go with a super easy Wix.com website, which is now published and works well. In searches I come up under wordpress only and my deleted wordpress website is still there. I want people to be able to find my wix site. I hope there is a way to TOTALLY delete my word press account. I will PAY you to do it.

Sorry, Charlie, no can do. I checked his email and his domain that he put in his email and it was on WordPress.com so I sent him the link on .com for How to delete your site.

I will note, I am sorry he wants to use Wix.com, but on some levels it is far simpler than WordPress (yes, I said it). It’s drag, drop, and done, and looks great on desktops. Mobile? That’s another story. But I had a paint-by-numbers GeoCities account back in the day, so I really don’t have room to talk about ugly first websites.

The story doesn’t end here. Charlie asked me to do it for him.

Even if he was a customer at my company, I would tell him no. I would send him directions on how to do it but I would not delete it for him. I don’t delete customer’s sites or data (unless the data is a Terms violation). Hell, even with hacked content, I back it up elsewhere first. Deleting someone’s data is an absolute, 100%, last resort. You should never ever do it. There’s no going back.

Then Charlie asked me again.

I suspect his issue was that he was really frustrated and wanted everything to die in a fire. Which I totally understand, but amidst all your anger, you need to take a deep breath and follow the directions. And, when someone tells you “I don’t work for that company, but I found out how to do it. Here you go!” perhaps you can say “Thank you.”

Just a thought.

16 October, 2015
Turning It Off And On Again
Apple’s watchOS 2.0 came out on Monday Sept 21, and I was one of the unlucky ones who had a problem. All of the new ‘native’ apps crashed.

If you’re unfamiliar with the concept, the original Apple Watch didn’t allow apps to really run on the watch. They ran on the phone and you had to use Bluetooth to connect for data. Now, with watchOS 2, the apps can load locally and use wifi on the Watch itself, making them faster. Exciting times for all. As I explained to my wife, all the Apple default native apps worked fine. The 3rd party ones did not. They all crashed.

Also my battery life went to shit. So I did what one logically does. I rebooted my Watch. That didn’t help. So I went to Google and Reddit (yes, Reddit) and I dug around and found what everyone else had done to fix it:
- Unpair and re-pair
- restore from backup of 2.0
- Setup as new
- Let it sit overnight
- Uninstall apps from phone, reboot phone and watch, reinstall apps on phone, reinstall apps on watch
- Reinstall from my 1.0.1 backup
None of that worked for me, so I filed a ticket with Apple support at about 7:15am. They called me back at 7:30 (which was nifty) and we discussed what I’d tried. They walked me through things, I confirmed I’d tried all of that, and detailed what I’d seen happen. Finally the woman apologized, said she didn’t know why it couldn’t work, and asked if I wanted to mail it in to Apple for a replacement.

I didn’t. I was sure this wasn’t a hardware bug. I asked if I could take it to an Apple Store, and she said yes, making me an appointment at the store for the weekend (the earliest time) but I work .5 miles from a store so I planned to head down after lunch to have a go.

I ended up not doing that.

I work in tech. I’m used to troubleshooting. I went over everything I’d done. I checked and double checked that I was sure I did it right. I went back to the Reddit thread and looked to see if anything new had been posted. Sure enough, there was something. A Zen man in the MacRumors forum had an answer:
- Doing a iphone backup with encryption of data on itunes.
- Delete content of iphone.
- Restore from a backup.
- All native apps are working fine!
While I couldn’t say that was a ‘great’ idea, I figured I had nothing left to lose. Since I always keep a spare cable for my phone and my watch in my bag, I connected them both and tried.

And yes. It worked. Immediately I canceled the appointment with the Apple Help Gurus and started a live chat with them to explain how I fixed it. I also contacted the two app companies I’d been chatting with about it and made sure to confirm on Reddit that it worked for me. Because I will never be DenverCoder9.

The debugging process with the Apple Watch is convoluted. I had a similar headache when I couldn’t get the WiFi working properly. I ended up having to disconnect WiFi from my phone and then re-add it for the Watch to pick it up. It’s not really the best experience, and there’s not a lot of ways to debug things.

While I do like the Apple Watch, the black-box technology aspect of the iPhone is increased since it’s, literally, impossible to use the watch without a phone. You have to both attempt to fix things on the watch and the phone, without having a way to determine which is the broken one. And a ‘reinstall’ is not really the friendliest thing. Had I not had a handy laptop, I would have had to do an iCloud restore, which would kill my activity history (something I’d already accidentally wiped out).

The problem comes back to meaningful error messages. All I could say was “The app crashes and kicks me back to the home screen.” Apple faces the same issues we all do with errors. How do we explain things in an informative way that allows people to react to the errors and know what to do next, when there is no way to gauge their skill set? Sadly, Apple’s route is “Take it to a professional.”

We can’t all do that with our products, and more often than not it leads to frustration and things like ‘Bendgate,’ where people just rant and make a product seem worse when it’s really only a very small percentage of those who are impacted.

Is there an answer? No. But it’s just one more thing to consider when we discuss elegant failures.
14 October, 2015
An Ad Network You Can’t Use

Amidst the kerfluffle of Peace being pulled from the App Store after a couple days, there was a mention of how it also blocked the Deck Network ads.

Most people in tech have seen Deck ads, but few outside the ‘hard core’ geeks know of it, and it’s for good reason. It’s an invite only ad system that makes ads that don’t slow your site down.

Manually curating ads, they restrict users to show one and only one ad on the site, perhaps not on all pages of a site, but just the one ad.

In essence, buying a month on The Deck gives you an exclusive showing on three percent of all the pages viewed for that month across all fifty-two sites and services. And there won’t be Google or other third-party ads diluting your exposure. The Deck ad is the only ad on the page.

It’s a phenomenal amount of work. And that would be why only fifty-odd sites are in. Peace happens to be on that network. But let’s put aside the whole ethics and morality of ad-blocking for a day.

The idea behind the Deck Network is everything I want an ad network to be. They pride themselves of relevancy to their network and only show ads relevant to the network. They only show ads they’re okay with seeing. As mentioned before, it’s an incredible amount of work, but it’s exactly what you’d want to see in an ad network. Ads that people would rather be relevant than, nessecarily, make money.

That’s really kind of the same reason as my I like Project Wonderful so much. With Project Wonderful, though, the quality of the ads is a little crowd sourced. If enough of us report an ad, it will likely get pulled but it will always be reviewed. With The Deck, it’s the other way. Nothing gets in that isn’t vetted first.

The amount of work that goes into that is exactly why, every time anyone says “I’ll pay you to put my ad on your site” I say “No thanks.” The whole mess of running my own ads, having them expire and rotate and change, is a hassle I don’t want to mess with. I don’t want to spend my time running ads, and I’m a one-woman-show here, folks.

The balance between making money and having relevant ads is tricky. I think, for the tech world, The Deck gets it right. But I doubt any of us will ever be on it.

12 October, 2015