Every blogging platform has “sharp corners.” The little edges that stick out and poke you every now and then. Sometimes the little things are the ones that catch you the most. Bump into the same sharp corner enough times, and it feels like it’s going to draw blood.

Yesterday I wrote a post about how to use WordPress shortcodes. The writing part was easy enough. I documented how I built my review index page. Getting the page to display correctly was not. In the course of about a dozen edits I learned a few things.

The square bracket character ‘[‘ was the source of more than an hour of frustration. Two things conspired against me:

• My main writing environment, Ulysses, the left square bracket means “lets start a new link token.” To remove the special meaning it must be proceeded by a backslash.
• The WordPress post editor uses square brackets to define shortcodes. The bracketed shortcode is a stand in for dynamically generated content. While normally not a problem, in a post about shortcodes, a few tricks were required.

Square brackets vs. markdown

The Ulysses text editor is unique because it tokenizes some of the ugly formatting in markdown. In a text editor (TextEdit, TextWrangler, etc.) a markdown link looks like this:

In Ulysses, the URL portion of the link is hidden, only showing the part a person can read. Here’s the same sample of text:

In Ulysses typing a square bracket is a shortcut to starting a link. If displaying one is the goal, it must be escaped with a backslash. Which looks like this: [

So far, so good. Now I can see what I’m writing. When I’m finished I select all, then choose File -> Copy As -> HTML which put my writing on the clipboard as nicely formatted HTML. Ready for pasting into the WordPress post editor.¹

Square brackets vs. WordPress

Normally, square brackets are displayed, well, normally. As in they show up directly as typed. But when discussing shortcodes and trying to show exactly how they work, you can’t just type the bracket enclosed shortcode. Even it’s wrapped in <code> or <pre> tags.

When WordPress sees the shortcode, it’s replaced with whatever that shortcode represents. The shortcode help page lists all the ones WordPress recognizes.

One interesting thing about the square bracket characters: They’re not recognized as special in HTML and are without a matching character entity references. They’re just text. The solution I used was to replace [ and ] with the matching HTML entity of [ and ] in the text I pasted into the post editor.

At first I did this by hand, because I was figuring out what worked. Again, this is something that should be at least partially automated. Computers are better at doing repetitive tasks than me.

The text filter

The text editing program TextWrangler has a neat feature—Text Filters. It will run selected text (or a whole document) through an external script and return the result. This is perfect for specialized search and replace jobs.

But first, a text filter has to be written.

Any shell script can be used, and I opted for a plain sed script. I created a file named Encode brackets in the Text Filters folder located at:

~/Library/Application Support/TextWrangler/Text Filters/

The file is a simple two-step sed operation that matches square brackets and replaces them with the HTML entity. The script looks like this:

#!/usr/bin/sed -f
s/\[/\[/
s/\]/\]/

Now when I open a file in TextWrangler, and choose Text -> Apply Text Filter -> Encode brackets all of the square brackets are converted.

For posts about shortcodes my workflow is:

1. Write post in Ulysses, using a backslash to escape any [’s that need to display.
2. Copy post text as HTML
3. Paste HTML into a new TextWrangler window.
4. Convert the text using my Encode brackets filter.
5. Select all, and copy/paste to the WordPress post editor.

Using text filters can fix a lot of little things that might crop up when writing about HTML and its formatting. When previewing this post, I noticed the ampersands (&) weren’t showing up as expected. I copied my Encode brackets script and changed it to this:

#!/usr/bin/sed -f
s/\&/\&/g

Which found and fixed all my stray ampersands for me.

Granted, these is an edge cases. But now I have a solution if this comes up in the future. My guess is 95% of bloggers would never run into this. But if you want to write about shortcodes or HTML entities in a post, I hope it helps you.

1. Why not use markdown directly in the post editor? Because I like to have a locally saved copy. ↩