Yesterday, after a week of working, polishing, and dithering, I published my first “how-to†post. Yay me.
I was really happy to find a plugin called SyntaxHighlighter Evolved to make my code stand out from the supporting text. It allows me to copy my source code into the post editor and preserve things like spacing while also highlighting different language elements.
But …
They say you should always include an image in a post, to help draw reader attention, alleviate the boredom of unbroken text, and so on. The only image I’d included was a screenshot of how the example plugin looks on the Dashboard -> Plugins page, so when I published a link to the new post on Facebook, that was the image that was used. Not terribly effective, and certainly not artistic. How could I make this better?
Rather than search for some stock image that might somehow be related to my post, I decided to take a screenshot of the code as displayed by SyntaxHighlighter. Nice and colorful, and certainly related to the post content. To make it more “artistic†I rotated and cropped it. That looked good.
Next came the fiddling.
First time around I simply inserted the image at the top of the post. It looked ok, but not great, stuck between the headline and the text. I suppose I could live with it, but to have it included as the image in social media links I should make it a featured image. (There’s a spot on the post editing page for doing that.)
Adding a featured image doesn’t always do anything for how the post looks on the website — it depends on the theme you’re using. Some themes use it for the header image, some display it only in lists of posts, some don’t use it at all. I’m currently using WordPress’ Twenty Thirteen theme, for the first time, so I wasn’t sure what would happen.
I pushed the Update button and then viewed the page to see what happened.
The image was there twice — once above the headline, and once below.
I went to the main page (which lists the most recent posts) and saw the image twice. This wouldn’t do.
I went back and edited the page again, leaving the “featured image†but deleting it from where I’d placed it in the post content. Update and check again.
This time things looked good. On the home page the featured image was placed above the headline, which was next to the start of the page content. Checking the post page revealed the same thing.
But …
All of my code extracts had been trashed. They were still there, but squished into a single line. What the heck?
I went back to the post editor, again, and switched it from “visual†to “text†mode. Visual mode is generally more comfortable for people because what they see is closer to what things look like when published. Bold text looks bold, italics looks italicized, etc.
Text mode shows you more of the underlying HTML tags that implement that bold and italic text. It still doesn’t show everything, however. Paragraph and line breaks, in particular, are sometimes hidden so that you don’t have to worry about whether or not they’re properly closed. WordPress takes care of that when the post is saved.
Unfortunately, in the process of saving, closing, and reediting, the new-line characters in my code samples had become converted into line break tags (<br />) which SyntaxHighlighter then interpreted as part of the code. Since there were no remaining new-line characters, the code was compressed into a single line.
In every single snippet. Grrr.
I wound up learning a lesson: Add the code snippets last, after everything else is polished to perfection. And do it in Text mode. Then preview and save, and don’t fiddle with it once it’s published.
Grrr.
