Category: How To

Dr. Jekyll and Ms. Hyde

I like WordPress. I like the community and I like the way I can invite other people in on it. But. I wanted to run a site, a small site, with static content for the most part, no comments, and just the basics. So why not Jekyll? After all, I’m big on self-hosting, and while most people I know seem to be running Jekyll on GitHub, you know me. I want to do it myself, I want to have it all here.

Six drinks later…

My major issue with Jekyll is that the ‘Simple’ directions aren’t obvious the way everyone seems to think they are. I mean, yes, they’re simple, but they lead you to some pretty crazy misconceptions based on how websites and CMSs work, and have worked, for a long time. And given all the posts I’ve read about how terrible WordPress is, my remark on that is: No, Jekyll is not terrible, but it has an audience.

Look, of course WordPress can be terrible. So can your car. It’s all in how you use it, what you add on to it, and what you fuel it with. I have a lot of reasons to use WordPress, and I really like it for many reasons (least of which is if you asked me to explain Jekyll to someone who emails me a PDF of a Word Doc to post on WordPress… Well, yeah, no, it’s not simple.)

Misconception: Where Do I Install Jekyll?

DaFUQ?

Okay… you think “Hey, Jekyll’s running my site so it’s all on Jekyll, right?” Nope! Jekyll is installed on my laptop. It’ll be used to create content that I will deploy to my website. Jekyll generates the webpages. Just bear with me. Yes, it also runs the site, but it doesn’t have to. In fact, it generates all of my pages into a subfolder called _site, which you can actually load as a webpage. If I copied all of that over to a folder, it’d work as is. So option one here is that I could just do that. But that’s not what I’d call ‘friendly’ and it means all my code has to be on the server where a sneaky person could go get it. Part of why Jekyll interested me is that it’s more secure by being a flat site.

Option two is to use a Jekyll ‘front end’ deployer, like Octopress or Prose. Option three was to stop and think “Maybe I just don’t get this and I should start simpler.” It’s very odd to me to have my ‘content’ on a server, but the ‘source’ not there. While if it’s just me running a site, that’s great. But as soon as I have to tell my dad to check code out… Maybe this is a bad idea. I don’t want end-users to have to learn all this. I want to tell them “Write your content. Save it here. Magic.”

Revise: Needs vs Wants

When I get really bogged down in thoughts like this, I step back and ask my self “What are my needs?” That’s similar to asking “What problem am I trying to solve?” but it’s a little broader, as I may not have an actual problem, I may just need a small change.

I’m looking for a product with a small footprint, no comments, a way to subscribe to updates (RSS or email), separate content and design (so my writers don’t mess with the layout), and it needs to have a workflow that does not involve me having to teach svn or git commands to a music major. Oh and it has to be easy for me to upgrade (one click or git pull will do).

Say what you will that git is easy (it is for me, albeit sometimes confusing). It’s not necessary for everyone to learn. I really feel a journalist shouldn’t have to learn to use it in order to write content! Still, after banging my head on this, I finally decided I was making my life too complicated by trying to self host before I understood the actual workflow of the process. So I went one step further back and decided not to self host right now.

KISS: GitPages

Everyone uses GitHub Pages. So fine, so will I. They walk you through the setup, so that’s nice. It was pretty painless to make a repo. But what did that have to do with Jekyll? I can edit everything within GitHub which is nice but I don’t want that. I wanted to learn Jekyll… Scroll to the bottom and there’s a nice graphic saying I can use Jekyll!

And they link to the Jekyll quickstart. Okay, thank you, I can install Jekyll. How do I hook them up? I had to actually Google to find the link to Using Jekyll with Pages and frankly, after reading it… I don’t want to. Oh I did it, but it’s not “simple.” It’s a total pain in the ass. It reminds me of the old MoveableType when you had to fuss with cgi-bin. It’s all manual. And this is fine for a dev, but I don’t want to have to install this on my Dad’s laptop. Did I mention he was on Windows?

So using this for a version controllable, static website, is actually far less tolerable than I wanted it to be. I can use it, I kind of understand it (the whole source folder is confusing me a little…) but it’s not something I could easily roll out to a medium-technical person without some serious training. In fact, I need some serious training to get good at just pushing my content, and when I compare that to WordPress…

I get why people like it, though. The static files alone are pretty cool, but it’s going to be a learning curve.

19 February, 2014
A Monstrous Regiment of Content
Any similarities to website configurations, current or defunct, is probably somewhat intentional. But I’m not naming names here in this tale of woe.

The situation:

You have your website: domain.com

You have a staging version where you test all your code: stage-domain.com

Your coders edit the theme code, install plugins, configure them, etc. At the same time, your editors edit content, make posts, etc. The code (plugins etc) is managed by Git because you know you should be using versioning. The posts are not because… WordPress.

The Problem:

In order to post content, you have to push code and content up to the production server. This means that if you’re trying to upgrade WordPress, you have to put a hold out on content until the upgrade is done. How do you keep the two in sync, without goobering your content?

An Answer:

Decouple content and code.

First let’s version control the php files. This means your themes and plugins will all be edited on staging, and when you’re done, you check the code in and then check it out on production.

Next we attack the DB. Have a job that, when you check out files in production, it copies up only following tables:
```
_options
_users
_usermeta
```
This means that all your code (plugin settings, theme settings, etc) gets pushed live, and all your content remains isolated. If you have extra tables, you may need to make allowances for them (like, say _podpress or _badbehavior), but you can find them quickly looking at the current DB. You’ll want to add these as necessary, or not. I’d count _podpress as ‘content’ and leave it out (we’ll get to what to do with it in a second), and _badbehavior as transient data.

On production, you have your content makers be Editors. They edit the content live (because you trust them). If you want to be extra secure, lock down the server via IP rules. At the end of every day, run a reverse sync, where the staging DB’s posts and content are replaced by the live site’s, thus ensuring everyone has the ‘live’ data. Obviously you’d want to script in a serialization safe search/replace after every sync (and have an auto-backup taken before any messing about starts).

It’s in the copy back that we decide what to do with the other files. Either make an exclude list or an include list, whichever makes you feel safer.

Includes would be:
```
_commentmeta
_comments
_postmeta
_posts
_terms
_term_relationships
_term_taxonomy
```
And then anything else you want like _podpress (see? I told you I’d get back to this).

Excludes would be anything I have in my push script from before, so _options etc. To this I’d also add _badbehavior or anything transient. I don’t really need it.

Pitfalls:

Content isn’t just posts and pages. What if your ‘editors’ need to edit widgets?

What if they don’t? StudioPress’s Genesis Framework has a totally awesome widget called “Featured Page” which lets you pick a page, check options, and off you go. What if you had a page called ‘Header Widget’ and in your widget area for Header, put that widget, pointed it to that page, and checked ‘Show Page Content’? Now your editors just need to edit that page!

What if they still do? Grab a plugin like Members and make a special role for “Super Editors” to let them make widget changes. Of course, now you have to uncouple _options and you’ve lost some of the magic here. This is a bad idea. You want to decouple content and code. Using Widgets for this is a cool idea, but what if you did it another way entirely. What if instead you used custom post types, and just had it show the most recent in the ‘spot’ for that header? Say you wanted an ad to show at the top of the page. Make your CPT for ‘header ads’ and write a post. Then schedule another for Wednesday at 3pm. Boom, your ad gets replaced! This also makes it easy to go a step further, make a Role for Marketing or Advertising, and now only they (and admins) can mess with ads. Downside there is you may end up with a lot of CPTs.

What about when WordPress updates? Well, that’s something to be careful over. If you update staging to (say) 3.5.1, but production is on 3.5, the tables will get updated. Thankfully, WordPress rarely messes with posts and comment tables. The ones that normally get poked with an update is _options, and we’re syncing that anyway. Still, you should set aside some time to test in staging before you go ahead and push this. Since we’re only posting content on production, this will have no impact on your editors.

Alternatives:

Put the content tables on another database. While WP doesn’t make it as easy as it does for custom user and meta tables, certainly you should be able to fiddle with that. Then just sync the rest of the tables. Code like hyberDB already lets you split the DB for load balancing, so you could fork that.

Or … Sync the whole database. But that defeats the purpose.
12 February, 2014
Giving Back Anew
One of the things that makes WordPress special is that people give back. Even people who make their living off WordPress via their plugins or themes give back in some way, be it testing new versions, submitting patches, or even making suggestions and asking questions. I got my start by giving back and answering low-tech questions in the forums.

Thus it’s natural that, while testing Easy Digital Download’s new version, I reported problems upstream:

And perhaps more natural that I made my first attempt at a patch on Github for it as well:

My code patch is a total of three lines. Four if you count the one I deleted. That’s all it takes to help contribute. You could even fix a typo.

What does this have to do with ebooks? The patch I submitted was for the display of the [downloads] shortcode, which will allow you to more easily display a flexible column list of your downloads. If you’ve seen my Catalog page, the books are listed with multiple items per line. But I’m not using any columns. With my code patch, you’ll be able to do this:

[downloads columns="0" thumbnails="true" orderby="title" order="ASC" buy_button="no" category="wp" price="no"]

Which outputs no columns and no breakpoints at all. Then you just need some CSS.
```
.edd_download_inner {
	float: left;
	width: 290px;
	margin-top: 10px;
	margin-bottom: 20px;
	margin-right: 15px;
	position: relative;
	height: 300px;
	padding-top: 10px;
	background: #F7F7F7;
	border: 1px solid #ddd;
	text-align: center;
}

.edd_downloads_list.edd_download_columns_0 {
	width: inherit;
}
```
Voila! Flexible columns!
31 January, 2014
Electric Sass Boogaloo
One I mastered using Sass enough to feel confident with basic mixins, I decided to remove my _media.scss file and go at it with Chris Coyer’s methodology of Breakpoints.

Instead of having a media file with all the special media calls, you can put the media section inside the Sass call. That stops that cognitive dissonance (for me at least) of hunting down where the heck I made that change. Since I was already using Tracy’s code, I was able to slip in breakpoints using her bp mixin, with a name. And thus:
```
.site-intro {
    @include font-size(14px);
    line-height: 1.5;
    @include rem(letter-spacing, 1px);
    text-transform: uppercase;
    float: left;
    @include rem(margin-top, 20px);
    @include bp(small) { @include rem(margin-bottom, 15px); width: 100%; text-align: center;}
}
```
This is clearly a really simple example, but it means I can add all sorts of blocks and have it be together. It actually made my building of my css files really easy, since once I figured out what size I wanted things to be, I was able to build and ignore all the tricky maths, which as I learned recently, was really important for your REMs.

Now that I was using includes, mixins, default settings, and breakins, it was time to reconsider how I made the css files. I installed sass on my laptops and servers. It required Ruby, but I’d installed that ages back trying out Jekyll (there’s no post about that yet for … reasons). Once Ruby was installed, Sass was this easy: gem install sass (you may or may not need to sudo that sandwich).

Having Sass on my server means I can edit files in place (which … you wouldn’t do, right?) and when I’m done, run this:
```
$ sass sass/style.scss style.css
```
But it also means when I (properly) edit on my computer and push up, I can script with git hooks instead! I took my methodology from Nico Hagenburger and Steve Grunwell, but you can use just about anything. I like how they don’t include the complied css file in their builds, which keeps it cleaner. Then one could have another hook to push the files after, say, you tag a release. That one would copy the files up to your server (rsync anyone?) and thus you do it all locally, but magically it appears to the world.

Breakdancing in Yoyogi, Tokyo, Japan. By Colin McMillen.

Back to breakpoints though. So great, I can use it to make my math teh simples. What else can I do? I can change content, colors, font-families, or anything else you want to change on a size-defined basis. How do you break the points? Breakpoint SASS is possibly my new favorite website.

For an end user who doesn’t really spend a lot of time with theme development, this buys even me a little time in my day. After I spent a weekend banging it out, I found my updates were easier, cleaner, and faster. Having the files separate is possibly the fastest thing. I edit a scss, check in the code to my git repo (because I am totally neurotic), test the compiled css, and I’m dancing in the streets.
24 January, 2014
Gaining REM
Not sleep… And not the band.

I was reading Breaking up responsive design on Yoast.com and, like pretty much everyone else, they’ve been been scaling down the browser base font to 62.5% for a while now. The default font-size for most browsers is, as it happens, 16px. The problem with that 62.5% call is that, at least on Chrome for Mac, I ended up getting a flash of 25.6px fonts before the page would load right. Turns out that wasn’t just me, and it’s the bane of 62.5%

So the fix would be to make my font 100%:
```
html {
	-webkit-text-size-adjust: 100%;
	font-size: 100%;
}
```
And then I’d have to re-do all my font calls in my CSS because they were all based on 14px. This made me stare at my child theme on another site for a while, and finally knuckle down and script in better font handling, because the idea of manually cranking through everything was too daunting, even if I used REM Calculator to sort out my px/em ratio.

Still, doing this still meant I’d still have a lot of stuff like this:
```
  font-size: 16px;
  font-size: 1rem;
```
Bah. Who want’s that? It was time to get sassier. I went back to Tracy and came up with her use of “Mixins.” And this is where Sass gets weird. It can do my math for me. This was, I admit, what originally made me interested. But in July it was a theoretical attraction. By December it was love. See, Tracy did the math with her sass-responsive library, which she calls a library of variables, mixins and formulas geared towards Responsive Web Design using Sass.

I called it _taupecat.scss but we’ll get to that in a second.

The first step would be to split up my files. See, I’m using Genesis, and they have a handy table of contents for all the sections, so I just made each section an import:
```
/*
HTML5 Reset
--------- */
@import &amp;quot;normalize&amp;quot;;

/*
Defaults
--------- */
@import &amp;quot;defaults&amp;quot;;

/*
Structure and Layout
--------- */
@import &amp;quot;structure&amp;quot;;
```
I admit, this gives me a million files, as you can see in that image on the right, but it’s actually pretty easy to figure out what’s where. It took me a while to get everything where I wanted it, and while I could have used Bones for Genesis, I know me, and like using Git is the fastest way to learn it, so is using Sass. So I started with the basics of splitting it up like imports. Also I didn’t want to add in Compass to my mix just yet.

I named my files _section.scss and they all consisted of the normal CSS for each section at first. After all, the first step is segregation of code. The second step was to use Tracy’s code and change all instances like this:
```
	margin-bottom: 24px;
	margin-bottom: 1.5rem;
```
to this:
```
	@include rem(margin-bottom, 24px);
```
And then
```
    padding: 0 12px 0 40px;
    padding: 0 0.75rem 0 2.5rem;
```
to this:
```
    padding: 0 12px 0 40px;
    padding: 0 cr(12px) 0 cr(40px);
```
This lets me use Tracy’s cool files and her hard work to make mine way easier! Basically I no longer have to math out that if 16px is 1rem, then 32px is 2rem, and that means 40px is 2.5rem and so on and so forth. It’s faster. Of course, since I’ve done this in pixels, it takes me a teensy bit longer to use inspector to fiddle, since I have to uncheck the rem and edit the px, but I’m okay with that.

I also tossed in two special calls:
```
@import &amp;quot;settings&amp;quot;;
@import &amp;quot;taupecat&amp;quot;;
```
The taupecat has all of Tracy’s code, and settings… well that’s for another post about how I’m controlling my colors and the fonts. But for now, well, all my font sizes and paddings are dynamic. It does mean I have to rebuild my css every time I make a change, but if you ask me, that’s better than math sometimes.

That’s why we have calculators, right?
15 January, 2014
Genesis Design for Gummies

You’re not a dummy, right, you know how to write and you know what’s good and what’s not, but the last time you had to edit your CSS your site went white. It’s worse now that you’re using this awesome theme called Genesis where every design is a ‘child’ theme that you don’t even want to edit because if WordPress taught you anything it’s that you don’t touch the plugin and theme files!

Well great. Now what?

I’m not a consultant. I suck at it, I hate it, and I don’t enjoy it. My friends the Norcrosses over at Reaktiv Studios are a dev agency that makes themes and plugins and even updates (they’re not paying me or compensating at all for this statement, I don’t even use ’em, I just like ’em). They’re good at it, and to make their life, and your life, easier, they came up with a new plugin called Genesis Design Palette Pro.

Previously, if you want to edit your theme, I would have said to use Jetpack’s CSS editor. Heck, that’s really what I do here, since it keeps revisions of your css changes. But most of what people change are the standard things that make your site look like an individual. The CSS is just a wall of weird, codey, text thing that made no sense when I first looked at CSS back in 1999. And that’s really how everyone did stuff back when Prince was en vogue.

But now there’s that nice Theme Customizer built in to WordPress that lets you edit the most basic (and most commonly used) aspects of your site right there and see the changes live! Wouldn’t it be nice if every theme let you play with its design like this?

Come here. Closer. The Genesis Design Pro plugin does that for you in a way that looks ‘right’ and familiar. Don’t believe me?

Looks familiar, don’t it? Okay, it’s not exactly the same, yet, but give it time. You can edit for mobile or desktop, adjust colors and padding with simple interfaces that are way easier for a lot of people to master than the weird CSS world. You can even add that freeform CSS if you want.

I think my only wish for it would be to have an export to css function, so I could design everything, save it, and then plunk it on a site as is.

10 January, 2014