Category: How To

Markdown Isn’t All Bad
It’s not a secret I hate markdown. It’s annoying to remember various commands, and one of the things I loved about WordPress from the start was that I didn’t have to learn bbCode or anything beyond the HTML I knew. When Jetpack included Markdown, I was a huge opponent. I thought it was useless and pointless and a waste of space.

I now use it in many of my posts.

You see, I don’t write in the visual editor. I used to, but there are ‘glitches’ with it. Like I couldn’t see the embed for Facebook (it showed up blank for some reason), and I had trouble embedding video content that required me to paste in script code. Then when I starting writing code, like I do on this site, I needed to make sure the formatting didn’t get mangled. It all boiled down to giving me two places where I use the Visual editor, and everything else is text.

That’s all well and good until I fell in love with my iPad mini.

You see I also have a major annoyance with the iOS app for WordPress. It’s too easy to post to the wrong site and it’s problematic when you want to upload featured images or make custom excerpts or have any custom post types. That means I use Chrome or Safari on iOS to write blog posts. If I’m offline, I write it up in Notes or Byword and just have it there until I’m ready to import. But I use WordPress in my browser because that’s where it works ‘best.’

Except HTML on an iPad is a pain in my ass.

It really, really, is. The number of clicks you have to do just to make a header, or strong text, is annoying. It’s three clicks to make an <h2> and it’s not even in the same place. It’s one click to get to the numbers, another (one up from where you hit to get to numbers) to go to advanced characters. Then you can press the button. Any chance I have to minimize my clicks means I can type even fast.

And you bet your bippy I’m fast at typing on my iPad.

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

John Gruber’s Markdown syntax primer is the only place that really took the time to make sense of Markdown to me. Everyone else just said ‘It’s what we use’ or ‘It’s faster’ or (worst) ‘It’s better.’

No. No. No. Better is what works for you. HTML, for the most part, works for me. And for me, a small subset of markdown syntax terms work very, very well to speed up my writing:
```
## Title

### Subtitle

&amp;amp;gt; Blockquote
```
There are a few more, like the codeblock (which I don’t use, since I like pretty formatting better) but the ability to use backticks and say <code> is pretty nice.

So do I like Markdown? No. It’s hard to remember ‘new’ syntax. But the ones I can use without having to close tags makes me a little happier and speeds me up a bit. For that, it’s pretty good. I can use it to enhance my HTML, and I wish that MediaWiki let me use HTML and Markdown instead of their woe begotten WikiSyntax. My kingdom for <table> in MediaWiki. Am I right?

Now. If I could just get John Gruber to increase his font size.
9 March, 2015
Packaging Code

I love that people do it. I hate that they don’t review it.

The number of projects I review, only to find that the author ran a tool like Grunt to combine files, but forgot to go over what the result was is fairly high. And this is a problem when you consider how many times I have to tell people “Your submission still has demo files, test scripts, and other files that aren’t applicable for distribution.” What happens is that people use the very cool auto-scripts and never stop to make sure that everything’s right. They make sure the code works but they don’t remember to clean up the package.

So let’s talk about what should never be in your plugins for WordPress.org

Deployment Scripts

Now I know a lot of people use scripts to copy their code from GitHub to WordPress’s SVN repo, and I think those scripts are great. They’re helpful, they speed up development, and please keep them out of your plugins. Your script should include a note not to distribute itself. I understand why, when you link us to the GitHub default zip, those scripts are in the review package, and that’s okay. But I do sometimes run a sweep through the repository to see how many people are accidentally including those SH files in their plugin packages. You’ve got to remove those. They don’t matter to the final product and without them, your plugin will be smaller.

Demo Folders

Here’s the thing. They don’t matter. A lot of awesome 3rd party tools come with detailed demo files and extensive things you’ll never need. Those demo folders also tend to be where you’ll find all sorts of crazy things like Google Analytics tracking, calls to external resources (like jquery’s JS files), and more. Your users will rarely, if ever, need that sort of thing. They generally don’t notice it, unless you code it into your plugin, at which point you’d be better served by making it look like WordPress.

Test Scripts

Your test scripts don’t need to be in your plugin. They’re cool, to make sure that the code is going to work before you push it, but that code doesn’t need to be in the plugin on my site, does it? No it does not. All automated tests should be separate from your plugin code files. People don’t need to see the Travis checks in the code on their sites. If they’re developers, they’ll go look for them at your code’s home, after all.

Compressed and Uncompressed Files

Pick one. You don’t need both. When you’re talking about a framework or a library, it’s fine to pull in a minified (but not p,a,c,k,e,r compressed) version of the file as your own version. If there’s no need or plan to edit that file (and there shouldn’t be), you can make the plugin smaller. Of course, I feel that if the JS is all of 7 lines, for goodness sake, it’s fine to leave it all human readable.

What Else?

What do people leave in plugin or theme packages that drive you up the wall?

4 March, 2015
Mailbag: Tools To Keep Consistent

Meg from Ohio (go Ohio!) asks the following:

You blog three times a week about tech. How do you keep doing that?

I schedule posts.

Chris Lema doesn’t, bless him. I started with about 10 posts I had in mind, sat down one day and made myself a buffer, and thought that it would be better to space them out to every other day. It actually started as twice a week, but then I bumped it to M-W-F, and since I’m kind of wordy, I’ve been able to keep up with it. Sometimes I write a post because I solved a problem, which happens pretty much every day, and sometimes I toss out a remark on twitter that people want to hear more about.

Much of it comes from listening and reading a lot. But I don’t just schedule posts. I use the plugin Editorial Calendar to keep tabs on what my schedule is, when things are being posts, and at what time, because I actually really hate the posts lists.

Here’s your default posts list:

It’s pretty bare bones and functional, but one of the things that’s always bothered me about the whole post list is how useless it is. Don’t get me wrong, it’s a list of posts, and it does that really well. But with the moving target that is what we use WordPress for, it’s become rather frustratingly bare bones for me and it really does impact my ability to get work done when I have to bounce back and forth between multiple screens just to see what the status is, verify I updated everything, and by the way, where are all my posts.

So, in the grand WordPress Tradition, I enhance it with plugins.

Admin Featured Image shows the featured image in the posts list, which is really good for one site to make sure I did too set an image and what it is.

UI Labs I’ve actually forked. I need to remember to ping John about this, because I took his (great) plugin and modernized it. If you’re interested, that code is up on my github UI-Labs repo. It’s slowly being improved to make things a little easier for me and to work on WP 4.0 and up.

Editorial Calendar, as mentioned before, gives me a great view for what’s scheduled and when:

The drag and drop interface lets me reschedule on a whim.

Speaking of… Schedule Posts Calendar fills a void that has pissed me off for years. Just look at the comparison:

First, there’s the calendar by the month, then there’s the date, and finally the epic button ‘today’ to let me fast fix posts messed up by the WP iOS app.

So how do I keep posting so often? You ask questions, I answer them, and I have some tools to make it simpler for me.

6 February, 2015
Mailbag: Trash the Blog Slug

If you only knew how many times I got this one…

When I made my multisite, it changed all the URLs on my main site from example.com/postname to example.com/blog/postname ! How do I change that!?

This is because you picked Subfolders for your network.

Now before you get into this, ranting that it’s wrong, please actually read all of https://core.trac.wordpress.org/ticket/12002 first. The initial ticket was that if you used subdomains, you were also locked into using /blog/. We’ve obviously fixed that, but it brought up a bigger issue.

Why do we keep it? To prevent conflicts. If you use /blog/%postname% and have a post named “humperdink” and another subsite named the same, it would cause a mess of problems. It’s one thing to search all your pages for possible conflicts (remember, your pages will still show up as example.com/pagename), most people only have a few pages. But once you factor in the hundreds of posts, it gets really crazy. If you have an open Multisite, where anyone can register any site, you have no way to doublecheck the URLs.

So we’re making sure we don’t conflict with posts and sites, which is pretty impossible to do without a massive DB query every time you post, as well as pages and sites (less massive). I think that we should have some slug in there for those reasons.

Or as Nacin put it when he detailed out a potential roadmap for Multisite:

Dealing with URL Conflicts

Perhaps the greatest change will be addressing the issue of the main site gaining a /blog prefix. This is ostensibly to avoid top-level pages on the main site from clashing with sub-sites. With arbitrary domain support (via domain mapping primarily, and secondarily via secondary networks), any site with path / can clash with any other site with the same domain but a different path. With multiple path segments (nested sites), any site with path /X/ can have pages that clash with site /X/Y/.

Ultimately, this requires two-way blacklisting. Before a site is created, it must be checked against top-level URLs of the possibly conflicting site. And, before a page is created, it must be checked against sub-sites that already exist. If an /about/ page already exists on example.com/, an /about/ site cannot be created. But if an example.com/blog/ site already exists, a /blog/ page cannot be created on example.com. This gets complicated quickly, and is a very strong argument for only supporting one path segment in core by default, and allowing plugins to handle these potential conflicts on their own. In most cases, simply ignoring the potential conflicts is going to be sufficient.

You see the headache? But hey, if you’re sure it won’t be a problem, you can do this yourself.

Edit the site via network admin -> sites

Click on settings and scroll till you find the permalink settings:

Remove blog and save. Done.

Now bear in mind, should you ever change permalinks on the main site, you will have to go back and do that again. This is because on the permalinks page, it’s hardcoded in:

Also some plugins will refresh permalinks and accidentally put it back in, so you need to be very careful. Someone wrote a cron job to re-write that value every hour in the DB.

30 January, 2015
Gallery Columns Zero
I have a site where I love using galleries but I hate having to define their width. That’s something I hate about WordPress’ Gallery shortcode, you have to define a width, otherwise it’s all one column. Ugly ugly.

The way that WordPress handles these columns also sucks. It puts in clear breaks:
```
<br style="clear: both" />
```
And frankly I hate that too.

But I don’t do that with this other software I use. In fact, I have it all nicely coded in to show all my images, and then toss one final clear break at the bottom, to … clear the breaks. And what that does for me is gives me an adaptive width gallery that will expand and contract with my content.

So how can I do that with WordPress?

The easy part is something I already do in EDD, and that’s to use a fake column value of zero: gallery columns="0"

That gives me a handy new column class: gallery-columns-0

And that is very easy for me to style, by overriding the width from 100% to auto (the !important is dreadful), and set up the padding I want.
```
/* Gallery */

.gallery-columns-0 dl.gallery-item {
	width: auto!important;
	padding: 0;
	margin: 0 10px 0 0;
}
```
But what about the ‘break’ afterwards? If you only need to support IE 8 and up, then it’s as simple as this CSS:
```
.gallery-columns-0:after {
	content: "";
	display: table;
	clear: both;
	padding-bottom: 10px;
}
```
The padding on the bottom is to make it match my site, adjust as needed. I’m sure I could use the post_gallery filter hook and the same code from the gallery_shortcode function but with my br modification, but 0.017% of people visit this site using IE 7 or less, and at that percentage, so much of the site will look terrible anyway.

The only real downside is that I have to manually enter the shortcode in text mode, since I can’t select ‘0’ as an option from the dropdown.
26 January, 2015
Mailbag: Have You Ever Split a Multisite?
That was the question.

Have you ever split a multisite? If so, how?

I wrote about Breaking Up Multisite before, but this was more specific.

Yes. And it’s a funny story.

I should preface the story with the reminder that in general when someone asks me how to do it, I casually mention that they can’t pay me enough to do it. This turned out to be inaccurate, as I was paid to do it. One of my first tasks at DreamHost was to take three separate sites and turn it into a two-site Multisite network. Two blogs were merged into one, then the new site was moved to Multisite. We did that with the export/import tools in WordPress. Fast-forward two years (my how time flies, Simon!) and now I’m asked to un-do it. But they only want site #2 now. The main site is being deleted.

I was actually glad, since this gave me a chance to handle the site properly and upgrade it correctly. I could clean out the old posts and content, re-sync users, tighten security, and undo the nightmare that was our old process. Plus the exercise of unraveling would give me more experience in WordPress shenanigans. And finally, it answered the question of how much you would have to pay me in order to do this (answer: more than most people would).

It started out as a massive 30 step process, but after running through it a few times, I was able to speed it up into five, simple, sections. I make use of WP-CLI here, but if you don’t have it you’ll want to get interconnectit’s search and replace tool to save you a migraine.

Bring it Local

I use Vagrant and I made example.dev for this.

Then I just copied down all the files from example.com/wp-content/blogs.dir/2/files/ to example.dev/wp-content/uploads-orig/ and did a database dump. Since I use WP-CLI, this was just a wb db export command.

That was the full database, though, all 64megs of it, and I only wanted the second site. But we’ll get there in a second. I knew I had WP-CLI on my test box, but if I didn’t, I would have zipped the file in order to use phpMyAdmin (which would make it about 6megs). I’m lazy. I like GUIs. Either way, I imported the entire database to my new server.

I also made a new wp-config.php file while I was at it, for multiple reasons. The one we were using did a check to see what domain you were on, and loaded different database params based on that. It was a cool bit of code, but it was unnecessary here. Making a new config file is easy (for me), and it ensured I had it clean and only set to a single install of WordPress. After all, I’m de-multisiting.

Fix the Tables

Of course, I had to clean that database. The first step was simple and I dropped all wp_FOO tables except wp_users and wp_usermeta. That left me with all the wp_2_ tables.

Next I renamed wp_2_ to wp_ so I could have everything nice and orderly. But there’s a catch there, becuase there’s an option in my wp_options table that has the name wp_2_user_roles. Can you see what’s wrong? I need that to become wp_user_roles and I need to update any usermeta.

Break out WP-CLI again and run this: wp search-replace "wp_2_" "wp_"

So nice. So easy. That actually took care of 100% of the issues with the table renames. Were I doing it manually, it would be time for tears in your beers.

Clean the Images

With WP-CLI this is a snap:
```
wp search-replace http://example.com/foldername/files/ http://example.dev/wp-content/uploads/
wp search-replace http://example.com/foldername http://example.dev
wp search-replace wp-content/blogs.dir/2/files wp-content/uploads
```
I ran it like that for a reason. I like to do my searches in order of smallest catch to biggest, and this way it kept my possible gaffs to a minimum. I knew I had to fix all the images and post content, so it was safer this way.

Clean up Users, Themes, and Plugins

We had a lot of old, duplicate, users who had no posts or had left the project. I went over everyone’s permissions, dropped them down as low as I could, and removed half the admins. It’s just a good time for that.

Next I reinstalled themes and plugins. I could have just copied them down, but I reinstalled everything because I wanted to take the time to make sure they were all clean and the latest versions. This is also where I paused to do a security review of everything we had.

Move it Live

Well now we’re just moving WordPress like normal. Copy it all up via FTP, copy up the database, run a last search replace to change example.dev to the real, new, domain (which I don’t actually know yet know), and it’s done. If I use wp-cli again, this will be as simple as running this: wp search-replace example.dev newsite.com

All that extra work I did before pays off here.

The nice thing about this is that I could have done this and then keep the main site if I’d wanted to. I didn’t, but I could have easily deleted all the wp_2_ tables and just cleaned up the multisite stuff. The headache is I’d have to do this multiple times if I’d had, say, ten sites on the network and wanted to move them all. If that had been the case, I would have only exported the wp_2_ tables and the wp_users and wp_usermeta ones.

But yes. I have un-multi’d a site.
23 January, 2015