Category archive: design 11 posts

F******k Instant Articles: How do they work?

Posted by Jer Clarke on July 21, 2017 · design · WordPress

This is the web version of my WordCamp 2017 talk about Facebook Instant Articles

Here’s the slides embedded from Slideshare.

Key links:


  • You run your own WP site
  • Mobile traffic is key
  • Facebook is a source of traffic for your content
  • You don’t want to use weird awful ad networks
  • Your soul is for sale

What is an iA and what does it do?

instant articles promo image

  • Posts load very fast in Facebook mobile apps
  • Replaces WP theme for posts viewed from Facebook mobile
  • Plugin sends posts to Facebook as raw data when saved
  • Facebook stores post content and renders them for mobile visitors
  • Does not “share” your posts, you do that the normal way with normal URL
  • Only applies to mobile apps, but that is the most common traffic

Okay but what is an AMP again?

  • Alternate version of a URL hosted on your site
  • AMP is a custom „theme“ WP uses on your content to match the AMP standard
  • AMP versions of posts get harvested by Google and stored in their cache
  • Fast AMP cache served to Google mobile visitors
  • Google gives your content special treatment in search (Carousel)

Why NOT use iA?

  • You hand control of your content to Facebook
  • Violates open web principles (walled garden)
  • You are subject to Facebook’s whims
  • Content must be crammed into very limited format
  • Some content not possible in iA
  • Complications integrating with WP plugins
  • Not all ads function
  • Interactivity features must be on Facebook‘s terms

Why use iA?

  • [Promo image]
  • Actually super fast
  • More useable and beautiful than most sites on mobile
  • Only ever uses your URL as the web address of posts (unlike AMP)
  • Analytics integration available
  • No load on your server from traffic wave
  • Advertising integration available
  • Facebook probably gives iA unfair advantage [citation needed]

Steps to set up!

Create a FB page

  • You can figure this out, I believe in you!

Initial plugin setup

  • Install Instant Articles for WP plugin and activate
  • Click „these instructions“ link to iA page activation screen
  • Choose your page, then accept the terms
  • Your page is now „activated“ for iA

Go to your Instant Articles Configuration screen inside Facebook (steps re-used later)

  • In Facebook visit your page
  • Click on Publishing Tools at the top
  • Click on Instant Articles ? Configuration in the sidebar
  • This screen is your real dashboard for iA setup, you will visit it a lot.

Get your facebook „Page ID“ for the plugin settings screen

  • In the Step 1: Set Up Instant Articles section, click on the Connect Your Site:Authorize your site link
  • First, insert your site URL in the Your Registered URLs field.
  • Copy the Page ID from the WordPress Plugin Users section
  • Return to wp-admin and the Facebook Instant Articles Settings screen.
  • Paste the ID you copied into the Facebook Page ID field.
  • Now the iA integration should be working, and you should see the iA metabox whenever you edit a post!

Set up a default Style Template

  • A style template is required to get approved, but can be very simple.
  • Go to your Instant Articles Configuration screen inside Facebook (see above)
  • Find the Tools section (below Initial Setup) and the Styles subsection.
  • Click on the default style to edit it.
  • The only MANDATORY thing is to have a Logo set for the article header (690x132px)
  • Configure the rest by preference, you can change it later anytime
  • Just make sure you have the Logo set up, so that you don’t get errors about it below.

Get 5 posts ready to publish Submit for Review

  • Overarching goal: Get the Submit for Review button in the wp-admin Facebook Instant Articles Settings screen to light up blue so you can push it!
  • We need to have 5 posts that have been submitted to iA by being saved after you have set up the plugin.
  • You can use existing posts, but they have to be re-saved
  • Edit your recently published posts and find the Facebook Instant Articles metabox
  • Move the metabox to just below the post for convenience, at least temporarily
  • Deal with any global errors you see that apply to all posts (see transformation debugging later)
  • Have 5 posts ready with no errors

Submit for Review!

  • Return to iA settings screen in Facebook
  • Find the Submit for Review button
  • Deal with any remaining errors (sorry)
  • Submit!

Testing your iA posts

    • iA only show on Facebook mobile apps, so testing is tricky
    • Basic: Share a post to Facebook, then view with a mobile app
    • Facebook Page Manager app (ios/Android) lets you preview posts without them being live on FB.
    • Use Page Manager to preview and design your iA while your review is pending
    • Also useful to preview iA without sharing to facebook
    • Getting to Page Manager previews:
      • Open Page Manager
      • Find your page
      • (more)


  • Instant Articles


Development mode

  • Sets your site to submit to Development rather than Production stream
  • Posts only visible in Page Manager app and Publishing Tools on Facebook site.
  • Useful when you are already approved, but want to test publishing with different configurations
  • Using Develpopment mode:
    • Enable Development Mode in wp-admin Instant Articles Settings
    • Change some settings (Style, transformations)
    • Resave an article, which will be submitted to Development rather than updating the Production version that visitors see.
    • Preview the new version in Development section of Page Manager app.
    • Disable  Development Mode in wp-admin Instant Articles Settings
    • Resave a post yet again, now submitting to Production with new settings
    • Check that the new post version is as expected in Page Manager app


  • iA uses a small subset of HTML5 as a strict markup standard
  • Transformations convert your standard HTML into iA markup
  • They can convert to an iA Format, or remove content entirely
  • Many useful WP transformations are built into the plugin

Transforming your problems into solutions

  • Transformations are added in the Custom transformer rules section of wp-admin iA settings
  • Uses JSON format, not very user friendly
  • Can be automated by plugins but not easy
  • Often you just need to remove items added by plugins (sharing tools)
  • Other times your custom styles (.pull-quote) can be converted into matching iA Formats

Debugging transformations

  • Errors for invalid markup will show in the WP post editor
  • Posts with errors just won’t submit, so it’s okay if some posts have un-transformable content
  • Forcing a post with errors to submit will mean the invalid content is just missing.
  • Establish editorial standards about how to solve common transformation errors
  • Some valid HTML combinations must be avoided to use iA consistently

Cover Images

  • Populated by WP Featured Image by default
  • Always show at the very top of posts
  • By rule, cannot be duplicated inside the post
  • Consider disabling Cover Image entirely if you insert your Featured Image in your posts


  • Production/development RSS feed: NO NEVER
  • Always have featured images!
  • Good luck with AMP integration!

Gender is an illusion

Posted by Jer Clarke on June 7, 2017 · design · Politics

Gender is an illusion spongebob

GIF by me and Giphy, thought it already existed but couldn’t find it.

Slides from my WordCamp Talk: Put A Map On It!

Posted by Jer Clarke on July 5, 2015 · design · GlobalVoices · WordPress

These are the slides for my talk at WordCamp Montreal 2015, about integrating maps and geolocation into your WordPress site with the Geo Mashup plugin. There should be video eventually and I’ll add it here :)

Full talk description

WordPress has built-in support for storing location information on posts, but no real way to make use of it. The Geo Mashup plugin enables deep, powerful geolocation in WordPress, letting you easily add geolocations (coordinates) to almost any content type. It also displays locations on maps you can embed in your theme, posts or widgets, with a dizzying array of options for what to show and how to display it.

This talk will start with the default geolocation system in WordPress and how Geo Mashup integrates with it. We’ll then cover the basics of setup and adding locations on posts, then the different map types and situations where you’d use them. We’ll finish with some dev considerations for displaying maps as elegantly as possible.

NetBeans Color Scheme: Solarized Dark with PHP Tweaks

Posted by Jer Clarke on August 17, 2012 · design · WordPress

Jump to download and installation instructions »

What is Solarized?

solarized logoSolarized is a programming color “palette” designed  by Ethan Schnoonover for use when writing syntax-highlited code. It’s based on color wheel and lightness relationships and it’s all sciencey and stuff, but the essence is that all the colors look good together and have good contrast, so you can use the different colors for different parts of your code (functions, variables, strings etc.) and no matter how you organize it the result should be easy on the eyes. It also has both a “dark” and “light” mode with different background/foreground colors, but most of the colors (red, green, magenta) work the same for both, which is cool.

Here’s a color reference I put together showing the various colors in Solarized Dark along with their RGB and hex codes. It was very useful to have around while working on the NetBeans theme (the Solarized site is strangely lacking a similar reference).

My Solarized Dark theme for NetBeans+PHP

As soon as I heard about Solarized I wanted to try it out with NetBeans, my IDE of choice for PHP/WordPress coding. I’ve spent many an hour tweaking my color schemes in NetBeans (and Smultron, my old text editor before that) and choosing the color relationships was always the hardest part, so having classy choices all laid out for me was very appealing.

The good news was that there is already a NetBeans port of the Solarized colors that worked as advertised. The problem was that IMHO it wasn’t particularly well executed. NetBeans has a lot of options in the color scheme settings, but they are also extremely confusing and often flat-out misleading, so I don’t blame the original author for not getting it perfect. He also may not have been looking at PHP code, in which case it makes sense that the PHP-specific color settings weren’t well organized. Lastly there’s a huge element of personal taste, even within the process of implementing a preset color theme like Solarized, so I recognize that the result is really just my personal opinion of what NetBeans+PHP+Solarized should look like.

All that said, here’s a screenshot of my NetBeans Solarized Dark theme:
Screenshot of my solarized dark theme for Netbeans

I like to think it balances the need to have different parts of the code be different colors and the limitations of doing so using the NetBeans color settings. It should work just as well with procedural and object-oriented code.

One feature I added that isn’t in the original Solarized for Netbeans colors is SVN support. I had to invent them, but my theme has appropriate red, green and blue background colors when viewing a SVN DIFF.

Installing my theme in your NetBeans

Since NetBeans has a configuration import/export system you can install these colors really easily.

  1. Download the .zip file linked below (don’t unzip it, NetBeans wants it as .zip).
  2. Open NetBeans and summon the Preferences window (Options on Windows).
  3. Go to the Fonts & Colors Preference tab.
  4. Click Import at the bottom of the window.
  5. Click Browse and find the .zip file, click OK.

Download »

Once you have the theme installed it should show up in the Fonts & Colors preferences as part of the Profile pulldown menu, where it’s identified as Netbeans_Solarized_Dark-jer.

Since I started using this I pretty much never feel the need to use a “light” theme so I haven’t tweaked the Solarized Light colors at all. Sorry if that’s what you would have preferred ;)

Anyway, hope some of you find this useful! I plan to someday get some of my changes added to the official GitHub repo, but wanted to get this out before my Code Faster and Smarter PHP with IDEs Like NetBeans talk tomorrow at WordCamp Montreal.

Video of my DRY CSS talk

Posted by Jer Clarke on March 7, 2012 · design · GlobalVoices

It’s not exactly a thrill ride, coming in at 51 minutes, but here’s the full audio+slides video of my presentation about DRY CSS, my “simple yet powerful CSS architecture that avoids duplication and increases design consistency by grouping shared properties together rather than redefining them over and over”. Sorry there’s not footage of my pretty face, I recorded this using Screen Capture in QuickTime and Voice Memos on my iPhone (using the earbud mic).

For the impatient, you can also go through just the slides on slideshare.

DRY CSS – Slides from my ConFoo 2012 talk

Posted by Jer Clarke on February 28, 2012 · design · GlobalVoices

Here’s the video with slides+audio of talk in case you prefer that. It’s 51min

This is an idea/talk that has literally been years in the making. Ever since I used this “DRY CSS” system for the Global Voices redesign I’ve been meaning to do the background research and lay it all out clearly like this. To me the core principle is so simple and standards-based that I have trouble believing it’s not already a thing, but I can’t find anyone else promoting it so here you go:

Embed should be above, here’s a direct link to the slideshare page: DRY CSS – A don’t-repeat-yourself methodology for creating efficient, unified and Scalable stylesheets »

Or if you prefer you can download the slides as a PDF »

Let me know what you think! Am I crazy? Why aren’t we already doing it this way?

Raven: My Custom Theme (Templates) for Munin

Posted by Jer Clarke on February 19, 2011 · design · General

This post is about Munin and the custom theme I built for it, Raven.

Click here to skip to the download and installation instructions if you just want the theme »

Click here if “Load average” means nothing to you.

What is Munin and why am I bothering with it?

Munin is a program you install on servers to track their resource usage and application performance on a minute-by-minute basis and present you with graphs giving tons of detail about it’s status over time (each report can be viewed for daily, weekly, etc.) It has lots of core and community-built plugins to track different server applications and different aspects of a server’s health.

The basic idea is that you install a ‘node’ on each server you want to keep track of, then one ‘master’ that queries the nodes and generates the graphs for you. I’ve had it recommended to me by pro sysadmins a few times in the past but was intimidated by the complexity of installation and the inscrutability of the resulting graphs, which depend on you having pre-existing knowledge of the command-line tools who’s output they aggregate. Oh, my iostat is up… um… what do I do about that?

The best guide to understanding and installing Munin I found was this great set of articles on the Slicehost blog. They are intended for Slicehost customers, but seem to apply pretty well to anyone using the Linux distrubutions they cover.

The problem with Munin and it’s Theme ecosystem

So I got it running and am trying to figure out how to read the information it presents but there’s a problem: It’s woefully, sinfully and abysmally ugly. The web pages output by munin are not just composed on 90’s style tables, they are ugly tables, with tiny text and wasteful spacing.

It seems the sysadmin crowd just doesn’t care about these things, because even though there is a really easy system for modifying and restyling the underlying HTML and CSS there is only one alternate template available on the whole internet! You can find it here in the Munin docs but it is almost as ugly as the default and the way you install it is completely counterintuitive and under-explained. On the bright side it has some really useful javascript features that the default doesn’t, if you can get it to work that is.

FWIW I don’t even know how to refer to this. The files themselves are called ‘templates’ in various places on the Munin site, but IMHO the package as a whole should be called a “theme”, at least that’s how we do things in WordPress land. I tried to use both in this post so people find this post, but I’ll call it ‘theme’ from now on.

My Munin Theme: Raven

Screenshot of Raven theme

Screenshot of Raven. Click to enlarge. Compare with screenshot of alt-default theme.

My answer to this problem is a new theme based on the javascript-enabled alternative from the Munin site. I call it Raven because Munin is named after a Raven ally of Odin, Norse king of the gods. Essentially it’s just the default theme with 80% of the ugly removed and a grey and white facelift. There is still a lot of work that could be done to actually fix all the ugly-ass HTML, but I want to see if this gains any traction before putting in the time.

Features of Raven compared to the default theme:

  • Javascript-enabled so the various sections of the ‘overview’ page are in tabs at the top instead of one never-ending page. (this is the most important usability improvement)
  • Larger text all over to actually use up all the empty space created by the unavoidably-large graph images.
  • Reduced unneeded spacing and <hr> tags that just added noise.
  • Calm light-grey colors and rounded corners to soothe your mind while you toil over server performance.
  • Readme/installation instructions in the .zip file.

Download Raven theme

If I get good feedback about this I’ll post it on the official Munin Wiki, but for now you can grab the zip file above. Please take a look at the contents and read the README-INSTRUCTIONS.txt file before installing the theme.

Installation Instructions

The README-INSTRUCTIONS.txt file contains all the information you need to use Raven, including detailed instructions with background information about the locations you need to upload files to. Here is the summarized instructions so you can get a sense of how simple installation is:

  • Upload the “templates_raven” directory from this zip file into your Munin config directory (i.e. same directory that munin.conf is in, probably /etc/munin/)
  • Upload the ‘raven-htmldir-files’ directory from this zip file into your Munin HTML directory (where the public HTML is served from).
  • Edit your “munin.conf” file on the master and change the “tmpldir” property to reference the new “templates_raven” directory in your Munin config directory instead of the default “templates”.
  • Wait 5 minutes for the Munin master to refresh itself and reload.

Feedback? Thanks? Bugfixes?

Obviously this is my first attempt at a Munin theme and there is not a lot of other examples to emulate, so I may have done something horribly wrong. If you have questions or comments please use the comment form below to let me know about them.

I will try to get back to you ASAP but be warned: I am not going to support your Munin problems for you. I am sharing this theme to give back to the community, but if your problem is complicated I may not be able to help.

Thanks in advance to anyone brave enough to try out the theme and leave feedback!

Nothing could brick our love

Posted by Jer Clarke on July 21, 2010 · design · photos

I miss your tiny hands, written on a brick

Prompted by Cardboard Love.

WordPress Admin Header Redesign: Light or Dark?

Posted by Jer Clarke on March 27, 2010 · design · WordPress

WARNING: Intense discussion of the open-source design of the WordPress website software lies ahead. I will literally discuss shades of grey. People uninterested in WordPress and its future should probably learn more about snuggies instead.

I updated my WordPress SVN Trunk installation today and noticed a huge change to the admin screens that had just been committed. The header and footer of the admin section had been switched from basically black to a very light grey color. This change was committed as a work in progress, so people would see it and work towards a final solution.

Fig 1. Old admin header color on top, current SVN version below.

Old WordPress header color and temporary new on in SVN

Overall I support this change and think it looks better, but the exact shade of grey in the background didn’t match the gradients in similar UI elements (the dashboard sections and screen options buttons) so I worked out a different light-grey graphic to use as a background that would match. Here is a screenshot of how it should look if this light grey is used in the final WP 3.0 release, I think it is pretty solid and shouldn’t make anyone cry.

Fig 2. WP-Admin with darker but still light-grey heading and footer. Pretty okay.

Screenshot of wp admin with light grey header and footer
Click to view full size

I remembered a conversation on the WP UI dev blog where another middle-grey option was proposed but didn’t get a lot of attention. I really liked the darker grey version in JohnONolan‘s original mockup so I worked out a full page screenshot using the darker shade of grey that I thought worked better and added them to the trac ticket about the header change.

Here’s the one I think would work the best, dark grey to match the active heading in the sidebar (in this case the “Dashboard” section heading).

Fig 3. Nice dark WordPress Admin screen, how it should be.

Screenshot of my proposed WP admin colorsClick to view full size

Here is one giant image with both of them so you can compare. Instead of images like this I like to open two versions in seperate tabs in my browser than jump back and forth to decide which I prefer.

Fig 4. Side-by-Side comparison of light and dark grey proposals for admin header and footer.

Side by side comparison of light and dark optionsClick to view full size.

I’m hoping the dark one can get implemented because it has a lot of nice features that the lighter version lacks:

  • It is not a big change from the old version, so people will be inherently less upset about it.
  • It brackets the whole UI nicely and preserves the high-contrast from the old design.
  • It avoids a page where 90% of the chrome matches each other pefectly. I think the dark grey is important to keeping the look neat, and having only one element in the page with that color (the active sidebar heading) make it look unbalanced.

Feedback welcome, what do you think? If you want to support/flame me the trac ticket about it is probably the best place, so that your input affects the final decision.

Global Voices does Valentines: Teach someone to blog!

Posted by Jer Clarke on February 12, 2009 · design · General · GlobalVoices

Back when there weren’t a lot of easy ways to start blogging elegantly I’d give blogs to any of my friends who showed interest, setting up Movable Type/WordPress/Blogger for them and working out simple templates I thought they’d like. Some of them are still up and going ( Mira, Woo! Room206, Speaks the Gimp, Tom Makes Pictures, A Collection of Works, The Creative Act, St-Francis Jigger, ) while others were abandoned a long time ago in favor of social networking or other hobbies (Brian, Princess Camp and Poison Frogs, Girl Riot, No, You’re a Blogger Geek, Lyss). Just making that list took me so long, I don’t think I ever added it all up like that before.

Anyway, these days I usually just point people at, since they have great themes, the best software around and an easy way to take it to the next level.

So what’s left to do? The other half of giving someone a blog: Showing them how to use it!

Global Voices Valentines Teach someone to blog or microblog

Global Voices’ core mission, aside from reporting on what’s happening in blogs all over the world, is to get more blogs and bloggers going whenever possible. Writing is good for you, it helps you clarify your thoughts and hone your writing, and it also helps people find you and keep up with you online.

GV is having a drive to get people to teach someone else how much fun blogging can be, or alternately blogging’s little cousin, microblogging (which means services like Twitter or similar to “status” on facebook but with more power and more fun. btw I’m almost always @jeremyclarke).

I signed the pledge to write about it and teach someone, but as the above list implies, my life is already pretty saturated with people I’ve taught to blog, so if you live in Montreal and want to learn how to blog (or want some advice about it too I guess) drop me a line and I can help you out sometime.

If you have someone in your life with problems getting their message out (or a business to promote, or any other problem that could be solved if they had a TV channel) then consider taking some time to show them how blogging could improve their life <3