0

Another question asks about creating a custom directory under the wp-content directory.

If there is a need for custom files e.g. CSS that need to be called, should a custom directory e.g. css be created under wp-content e.g. wp-content/css?

The function wp_upload_dir() returns the path to the wp-content/uploads directory and there doesn't appear to be a function to only return the path to wp-content.

Does this mean that custom directories such as the css directory should be created under wp-content/uploads instead?

An article on adding CSS or JavaScript resources suggests uploading these to the root of the child theme directory. What if there are other custom assets e.g. fonts?

In contrast another article recommends creating a sub-directory in the root directory e.g. public_html/subdirectory

13
  • I'm voting to close this as "opinion based" - there is no definitive rule here. However, each of the suggested methods has various implications and might not work in every case. For files uploaded by users I'd always go for wp-content/uploads/ - for files shipped with the extension I'd always go for the (child) theme / plugin itself.
    – kero
    Aug 24, 2021 at 9:36
  • 1
    IMO this is an anti-pattern and a poor idea. It's extremely rare that this is necessary, and would depend on edge cases and the context. Generally it is not a good idea to mess with the WP folder structure beyond a subfolder install ( a separate WP Content folder and WP folder, which simplifies WP installs that use git or package managers to install and WP by avoiding nested folders ). Sadly, you will get mainly subjective answers to this, there is no canonical "correct" answer to fit all situations
    – Tom J Nowell
    Aug 24, 2021 at 11:09
  • @kero - I'm unsure why it would be opinion base. Even though there is no definitive rule. I'm assuming that with the collective knowledge of WordPress experts, there would be recommendations. The use case examples I have are, when using third-party libraries e.g. bootstrap, lozad, etc that are enqueued using the a child-theme functions.php. These are not installed or deployed using plugins.
    – Ryan
    Aug 24, 2021 at 18:58
  • @TomJNowell - The context is using third-party libraries such as bootstrap, lozad and localized fonts (that are not packaged with WordPress core or the theme). Since I don't want to be introducing a change that may be disruptive to the native directory hierarchy, I'm seeking guidance as to the best practice (even if there isn't a canonical answer).
    – Ryan
    Aug 24, 2021 at 19:02
  • 1
    Also, you may find it difficult to get a consensus out of people, there is no codified best practice here, though you may notice more experienced developers leaning in a particular direction of sticking to WP's folder structure
    – Tom J Nowell
    Aug 25, 2021 at 9:13

2 Answers 2

2

If there is a need for custom files e.g. CSS that need to be called, should a custom directory e.g. css be created under wp-content e.g. wp-content/css?

No, never. You should not do this under any circumstances.

A themes assets belong in the theme. A plugins assets belong in that plugin. The only exception is when a child theme uses assets in its parent theme. Doing otherwise would be considered negligent by most WordPress developers, and a major red flag to many employers.

A themes folder should contain everything. It should not reference or store assets in a custom folder under wp-content.

This goes for anything your theme needs that isn't included with WP core or a parent theme. JS, CSS, JSON, PNG, PHP, etc etc. You can require the use of a plugin for functionality, or use a parent theme, but don't place parts of your theme in subfolders outside the theme folder. Likewise with plugins.

What Are The Consequences?

Here is a partial list of consequences, though many more exist:

  • Your theme would immediately fail wp.org review, as well as the review of theme market places
  • Automated tooling for testing and checking would no longer function correctly
  • The theme upload page would no longer fully install your theme as it doesn't know about your custom folder
  • Theme updates would no longer fully update your theme
  • Multiple themes that do this would cause conflicts, particularly on Multisite installations
  • Caching and optimisation plugins may break the assets you placed in the custom folder, or fail to pick them up
    • poorly built caching plugins may even use a css subfolder and overwite your work. A well built plugin would instead use the uploads folder ( you should not use the uploads folder for theme assets, this has security and practical consequences )
  • your theme will break on some enterprise grade and managed hosting due to folder mapping tech that doesn't account for the custom folder
  • certain CI deployment processes would need manual modification to account for the folders or they'll be stripped out on deployment
  • Unexpected folders in wp-content imply that the site has been compromised
  • Incompatibility with composer
  • Incompatibility with WP CLI

What About Subfolders Inside My Themes Folder?

Inside your theme you can organise assets however you want, it's up to you. Put them in the root, put them in subfolders, it's your choice and there is no required location for theme sub-folder structure.

The only CSS file that needs a specific location is style.css which must be in the root as WordPress looks for it to read the theme name etc. Likewise top level PHP templates and functions.php go in the root folder.


When Might Custom Folders in wp-content Make Sense?

They never make sense for theme developers.

The only time I've seen custom non-standard folders used in the wp-content folder are as follows:

  • vendor folders created by the composer tool for PHP dependencies
  • subfolders for CI such as .gitlab, or .github if your site is in version control, that aren't used by WP or the site, but are a part of the development process
  • folders required by hosting platforms, usually a sign of an unusual architecture at an enterprise level. A common example is when a hosting provider uses plugins-mu and provides a second folder for client mu plugins ( also a sign that it never occurred to them to load that code with a drop in file and let the client use plugins-mu )

You may find some caching plugins use a cache subfolder, but there's no reason this can't be moved under uploads/.

In general, good reasons to make new subfolders in wp-content are 1 in a billion, and almost always a sign that something has gone wrong in the development process. Those edge cases that are allowable have nothing to do with the running site or are part of unusual high end hosting setups

Then Why Does The Article Recommend wp-content/css?

It doesn't.

In contrast another article recommends creating a sub-directory in the root directory e.g. public_html/subdirectory

This article does not recommend this. You are mistaken. It recommends a subdirectory of the themes folder, not wp-content. E.g. wp-content/themes/yourtheme/css

The TLDR

  • Put your themes assets inside your theme
  • Put your plugins assets inside your plugin
  • Unless you absolutely require it and it is unavoidable, don't create non-standard folders in wp-content
    • It's very likely that you don't require it, consult with other WP devs, these situations are extremely rare
    • If you need it for a theme, something has gone horribly wrong
8
  • Should subdirectories be created under the child theme e.g. wp-content/themes/child-theme/css?
    – Ryan
    Aug 27, 2021 at 20:17
  • If you want to create subfolders inside your child theme you can do that, it is entirely up to you and personal preference. Create them, don’t create them, ¯\_(ツ)_/¯ there is no right answer for that
    – Tom J Nowell
    Aug 28, 2021 at 9:30
  • As a clarification why should It should not reference or store assets in a custom folder under wp-content? What are the implications/side effects?
    – Ryan
    Aug 28, 2021 at 19:37
  • lets say your theme was distributed in any meaningful way, the assumption everywhere is that a theme is self contained, which is the same for plugins, and lots of other packages in PHP/WordPress/Other CMS's/etc. even the assets you speak of come as singular packages. If you were to take a big chunk of your theme and place it in a subfolder as you describe, how would those files get there? The themes panel doesn't support moving files out of the theme, nor does any of the tooling. It would require users to manually move the files and create the folder, or for the theme to do it automatically
    – Tom J Nowell
    Aug 29, 2021 at 13:52
  • And if it did it automatically, why bother in the first place? It would fail on a lot of systems due to security measures, would get picked by various security software as suspicious, and it conveys zero benefits. And what if a second theme wants to do this? Now you have conflicts! And if the theme gets deleted or removed there's now folders left behind. What if your theme gets updated? WP will delete the folder then replace it with the new one, but it doesn't know about wp-content/css. Neither do a lot of plugins that might optimise it. Then there's caching rules that don't account for it
    – Tom J Nowell
    Aug 29, 2021 at 13:55
0

Yes you can create a directory within the wp_content directory. For example you can create wp_content/css as you have described for special cases only. However, using child theme for custom CSS files is advisable.

To access the wp_content directory, you can use the WP_CONTENT_URL constant. Example usage:

wp_enqueue_style( 'my-custom-style', WP_CONTENT_URL . '/css/style.css', array(), wp_get_theme()->get( 'Version' ) );

Also, you can use the WP_CONTENT_DIR constant to access the files in custom directories in wp_content. To access the CSS file use:

include WP_CONTENT_DIR . '/css/style.css';
1
  • Thanks. Is this the recommend practice? What alternative is there to the WP_CONTENT_URL constant if the output needs to return an absolute path e.g. /home/public_html/wp-content?
    – Ryan
    Aug 24, 2021 at 19:03

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.