Function Documentation

WordPress Function Documentation Progress

Writing Plugins: Directory Structure

If you plugin is fairly simple and small, you can contain your plugin in one file and have translations in the same directory. However, if you ever plan to extend your plugin and create more complex and feature complete, then you’ll want to rethink the single file method.

The only reason you would not use this method, is if you have optimization in mind and include all the library code in one file to prevent file access overhead. However, in most instances, if your library is massive, it is probably better to have the files separated for maintainability.

Separate Translated Files (.mo) Directory

It would serve your plugin better, if translated files were in their own directory, that way, when you setup the plugin textdomain, you can reference that one directory for WordPress to look into. Also, it would allow for easy management and cleaner plugin root structure.

Third Party or External Library Directory

For third party libraries that are used, it is better to place them all in another folder and could call it third-party/. This will create a separate from your plugin’s code and code that is external from your code. When people go to file bug reports you don’t want them to file bug reports with you that they should be filing with the respective library maintainer.

Using that name will give a hint that the files are not maintained by you and should have the defects filed elsewhere. It may not stop everyone from reporting the defects to you, but if you keep notes, it should be more informative to most WordPress power users.

Library Directory

The idea is to have at most two files in the root, a readme and your base plugin file. The readme to inform users on how to use your plugin, how to uninstall your plugin, and other information about your plugin. Your base plugin file has the WordPress required comment with your plugin data, so that WordPress knows about your plugin and can activate it. The base file will set up all of the plugin variables and include the required files.

The rest of your library will be contained in a folder in your plugin’s directory. You can use one file for optimization or for maintainability, separate the functionality out into logically named files.

Public CSS/JavaScript Directory(-ies)

If you plugin also has public CSS and JavaScript files, it is better to have them in their own directory. It allows for quick access to all of the individual files for CSS and JavaScript. It creates a separation, so that users know where to look for your CSS and JavaScript. Another advantage is for permissions, but those might need to be set by the user.


The idea is to create a separation of content, so that your plugin is more maintainable for both yourself and others. It is a suggestion and developers have their own style. I have no complaints other than you should be consistent. That is not to say that if you have one plugin with directories like the above that all of your plugins should be that way. No, it is to say that if you use directories for one thing, then you should split all of your content into directories.

January 20, 2008 Posted by | Writing Plugins Series | Leave a comment