5 min read

Common mistakes in WordPress Theme Development

Common mistakes in WordPress Theme Development

Last modified

This post will let you know about common mistakes in WordPress theme development and also tell you how to avoid them.

Template Tags:

WordPress template tags are very useful functions that are used in template files for dynamically generating content and customization. Below are some of template tags that should not be neglected while developing WordPress themes.



It’s a safe a way to include a CSS file to a head/footer of a WordPress generated page. People hard code stylesheets in header.php that is a bad practice. Even style.css shouldn’t be included in header using link tag. Always use this function for adding any CSS to header or footer.


This function is used to include JavaScript files in header/footer. You can specify dependencies for a script and it will also load dependent scripts if not already loaded.


This function should be used to get link of style.css of current theme/child theme.


Whenever you want to get directory path for currently activated theme, above function should be your thing.


Every time when you want to include some JS, CSS or want to put img tag use this function to get theme directory URL. Beware that if you are using some child theme you should use get_stylesheet_directory_uri() instead because this function will always return the directory URL where style.css reside but get_template_directory_uri() will return parent theme directory URL.


the_permalink() function returns link to the post being displayed inside the loop.


This function should be used when you want to get URL to some arbitrary post.

Wrong way: <a href=”<?php bloginfo(‘url’)?>/some-page”>Some Post</a>

Right way: <a href=”<?php echo get_permalink($some_post_id);?>”>Some Post</a>


Never forget to put wp_head() before closing tag in your header.php, as this is the function that will print JS, CSS and other stuff that is registered for header using wp_enqueue_style() and wp_enqueue_script(). Huge number of plugins use this hook to load necessary CSS and JS scripts. Forgetting this hook will break most of your installed plugins.


This function should be present in your footer.php before closing body tag. This will print CSS and JS scripts that are registered for footer.


Generic/Non unique Function Names:

functions.php provides you the liberty to add theme related function. Choose function names carefully because a generic function can cause your site crash. Yes, this can happen when you install some third party plugin and that function name was used in that plugin, PHP will return you a fatal error and site will go down. So always put some unique prefix to your functions. For example scriptbaker_tag_cloud() will be more safe than tag_cloud()


Actions and Filter hooks

As I said earlier that one should never put javascript or link tag inside header or footer and always use wp_enqueue_scripts () function, but how this function will print the scripts and stylesheets in header/footer. This is because of hooks, you can add a custom action for the wp_enqueue_scripts hook and register as many scripts and stylesheets as you want. And wp_head() and wp_footer() functions will take the responsibility to print your stylesheets and scripts.


Quicktags and Shortcodes in themes

Although majority of themes come with shortcodes but I am not in favor of them. Lets suppose you are developing a theme with responsive grids. You would like to provide user an easy way to create grids by using shortcodes and placing content inside them. And this idea looks cool because site admin will be able to create layouts without knowing anything about HTML/CSS. If shortcodes are this much useful then why I am not in favor of them. Purpose of a theme is to control look and feel of your website and present content in a fashion you want, content should not be dependent of a theme. Did you think what will happen if in future your client switch the theme, gazillion of pages and post will have broken content with shortcodes in plain text. If you feel you are limited by a need for shortcodes, put them in a plugin where they belong, or better still, choose one of the already existing, excellent plugins out there and build support for it into your theme.


Custom post types in themes

As you know theme is used to skin your website content, content should not be dependent of a theme. Anytime when you switch your theme content should be there with new look. But if you create your custom post types in functions.php of your theme, imagine you have created a custom post type books and there are thousands of books exist in your website. One day you decide to change website theme and you install that super awesome theme. But you will end up with all your books disappeared from your side, why because you just activated a new theme and older theme is not longer in use. What we learned from this example is that avoid adding functionality in theme, leave your theme just for presentation layer. Rest of thing should go in some plugin that you should ship with your theme.


Tinymce image styling

When you insert images in post/page content and use image alignment options provided in tinymce, tinymce adds some CSS classes on image tags. These classes are used to position images while rendered on front-end. Never forget to put the following css into your style.css file to make sure your you can align your images using the visual editor.


img.alignright {float:right; margin:10px 0 1em 1em}
img.alignleft {float:left; margin:10px 1em 1em 0} 
img.aligncenter {display: block; margin-left: auto; margin-right: auto} 
a img.alignright {float:right; margin:0 0 1em 1em} 
a img.alignleft {float:left; margin:0 1em 1em 0} 
a img.aligncenter {display: block; margin-left: auto; margin-right: auto}

Styling WP core widgets

WordPress comes with some default widgets like Calendar, Search, Tag Cloud and others. These widgets can be dropped in any sidebar. You have to handle them via CSS, all necessary styles should be present in style.css to correctly display core widgets.


Direct changes in Premium themes

Whenever you need to customize a premium WordPress theme, create a child theme and then do all customization in that child theme and don’t make any change in parent theme. This will make your child theme upgrade safe, meaning that whenever author of the premium theme releases a new version, you will be able to safely upgrade to newer version without losing customization.