Skip to main content

Course Progress

Loading...

WordPress File Structure Overview

Duration: 45 minutes
Module 4: Session 2

Learning Objectives

  • Understand the complete WordPress directory structure
  • Identify core files and their purposes
  • Learn which files to modify and which to avoid
  • Understand the role of each directory
  • Master WordPress file organization best practices

Introduction

Understanding WordPress's file structure is crucial for development, debugging, and maintenance. This knowledge helps you navigate the system, make modifications safely, and troubleshoot issues effectively.

💡
Important Rule
Never modify WordPress core files directly. All customizations should be done through themes, plugins, or the wp-content directory.

Root Directory Structure

Complete WordPress File Tree

graph TD A[WordPress Root] --> B[wp-admin/] A --> C[wp-content/] A --> D[wp-includes/] A --> E[Root Files] B --> B1[admin files] B --> B2[css/] B --> B3[images/] B --> B4[js/] B --> B5[includes/] C --> C1[themes/] C --> C2[plugins/] C --> C3[uploads/] C --> C4[languages/] C --> C5[upgrade/] D --> D1[PHP libraries] D --> D2[JavaScript] D --> D3[CSS] D --> D4[Functions] E --> E1[index.php] E --> E2[wp-config.php] E --> E3[.htaccess] E --> E4[wp-load.php] E --> E5[wp-settings.php] style A fill:#0073aa,color:#fff style C fill:#21759b,color:#fff style E fill:#46b450,color:#fff

Directory Overview

Core Directories Explained

1. wp-admin Directory

Purpose: Administrative Backend

Contains all files for the WordPress admin dashboard. This directory powers everything you see when logged into /wp-admin/.

wp-admin/
├── css/                 # Admin stylesheets
├── images/             # Admin UI images
├── includes/           # Admin function libraries
├── js/                 # Admin JavaScript files
├── maint/              # Maintenance mode files
├── network/            # Multisite network admin
├── user/               # User admin files
├── about.php           # About WordPress page
├── admin.php           # Admin bootstrap file
├── admin-ajax.php      # AJAX handler
├── customize.php       # Theme customizer
├── edit.php            # Posts list
├── index.php           # Dashboard
├── options.php         # Settings handler
├── plugins.php         # Plugin management
├── themes.php          # Theme management
├── upload.php          # Media library
└── users.php           # User management
⚠️
Warning
Never modify files in wp-admin. Updates will overwrite your changes.

2. wp-includes Directory

Purpose: Core WordPress Functionality

Contains the majority of WordPress core code - classes, functions, and libraries that make WordPress work.

wp-includes/
├── blocks/             # Block editor blocks
├── certificates/       # SSL certificates
├── css/                # Frontend CSS
├── fonts/              # System fonts
├── images/             # Core images
├── js/                 # Frontend JavaScript
├── php-compat/         # PHP compatibility
├── pomo/               # Translation library
├── rest-api/           # REST API endpoints
├── SimplePie/          # RSS feed parser
├── sodium_compat/      # Encryption library
├── widgets/            # Widget classes
├── cache.php           # Object cache
├── capabilities.php    # User capabilities
├── class-*.php         # Core classes
├── cron.php           # Scheduled tasks
├── functions.php      # Core functions
├── pluggable.php      # Overrideable functions
├── post.php           # Post functions
├── query.php          # Database queries
├── taxonomy.php       # Taxonomy functions
├── theme.php          # Theme functions
├── user.php           # User functions
└── wp-db.php          # Database abstraction

3. wp-content Directory

Purpose: User Content and Customizations

The only directory where you should make modifications. Contains themes, plugins, uploads, and custom code.

wp-content/
├── languages/          # Translation files
│   ├── plugins/       # Plugin translations
│   └── themes/        # Theme translations
├── mu-plugins/        # Must-use plugins
├── plugins/           # Installed plugins
├── themes/            # Installed themes
├── upgrade/           # Temporary update files
├── uploads/           # Media uploads
│   └── 2024/         # Year-based organization
│       ├── 01/       # Month folders
│       └── 12/
├── cache/            # Cache directory (optional)
├── backups/          # Backup files (optional)
└── index.php         # Directory protection
✅
Safe to Modify
wp-content is your playground. All customizations should happen here.

Root Level Files

Essential Root Files

File Purpose Modifiable?
index.php Main entry point, loads WordPress ❌ Never
wp-config.php Configuration settings ✅ Yes (carefully)
.htaccess Server configuration (Apache) ✅ Yes (carefully)
wp-load.php Bootstrap WordPress ❌ Never
wp-blog-header.php Load WordPress environment ❌ Never
wp-settings.php Runtime settings ❌ Never
wp-activate.php Multisite activation ❌ Never
wp-signup.php Multisite registration ❌ Never
wp-login.php Login page ❌ Never
wp-cron.php Scheduled tasks ❌ Never
xmlrpc.php XML-RPC API ❌ Never
wp-links-opml.php Links export ❌ Never

WordPress Bootstrap Process

How WordPress Loads

graph TD A[Browser Request] --> B[index.php] B --> C[wp-blog-header.php] C --> D[wp-load.php] D --> E{wp-config.php exists?} E -->|Yes| F[Load wp-config.php] E -->|No| G[Setup Configuration] F --> H[wp-settings.php] H --> I[Load Active Theme] H --> J[Load Active Plugins] H --> K[Load Functions] I --> L[Template Loader] J --> L K --> L L --> M[Render Page] style A fill:#f9f9f9 style B fill:#0073aa,color:#fff style F fill:#21759b,color:#fff style M fill:#46b450,color:#fff

Load Order Visualization

File Naming Conventions

WordPress File Patterns

# Common WordPress file naming patterns

# Class files
class-wp-*.php          # Core WordPress classes
class-*.php            # General class files

# Template files
single-*.php           # Single post templates
page-*.php            # Page templates
archive-*.php         # Archive templates
taxonomy-*.php        # Taxonomy templates

# Include files
inc/*.php             # Include files
includes/*.php        # Include directory

# Admin files
admin-*.php           # Admin pages
*-admin.php          # Admin functionality

# AJAX handlers
admin-ajax.php        # Main AJAX handler
*-ajax.php           # Component AJAX

# API files
rest-api/*.php       # REST API endpoints
class-wp-rest-*.php  # REST API classes

Important Configuration Files

Configuration File Locations

Key Configuration Files

  • wp-config.php- Main configuration (database, keys, debug)
  • .htaccess- Apache server rules and permalinks
  • php.ini- PHP configuration (server level)
  • nginx.conf- Nginx configuration (if using Nginx)
  • robots.txt- Search engine crawling rules
  • wp-content/debug.log- Debug output (when enabled)

Environment-Specific Files

# Development environment files (add to .gitignore)
.env                    # Environment variables
.env.local             # Local overrides
wp-config-local.php    # Local configuration
.DS_Store             # Mac system files
Thumbs.db             # Windows thumbnails
*.log                 # Log files
*.sql                 # Database dumps
node_modules/         # NPM packages
vendor/               # Composer packages
.git/                # Git repository

WordPress Multisite Structure

Additional Multisite Files

# Multisite-specific structure
wp-content/
├── blogs.dir/         # Legacy media uploads (pre-3.5)
│   ├── 1/            # Main site
│   ├── 2/            # Site ID 2
│   └── 3/            # Site ID 3
└── uploads/
    └── sites/        # Modern multisite uploads
        ├── 2/        # Site ID 2 uploads
        └── 3/        # Site ID 3 uploads

# Additional multisite files in root
wp-activate.php       # Network activation
wp-signup.php        # Network signup
sunrise.php          # Domain mapping (wp-content/)

File Structure Best Practices

  • Never modify core files- Use hooks, filters, and wp-content instead
  • Organize uploads by date- Helps with backup and management
  • Use child themes- Preserve customizations during updates
  • Keep plugins organized- One plugin per directory
  • Regular cleanup- Remove unused themes and plugins
  • Backup before updates- Always backup files and database
  • Use version control- Track custom code changes
  • Document customizations- Keep notes on modifications

Typical WordPress Installation Size

# Fresh WordPress installation
Total Size: ~50 MB

Breakdown:
├── wp-admin/     15 MB  (30%)
├── wp-includes/  25 MB  (50%)
├── wp-content/   8 MB   (16%)
└── Root files    2 MB   (4%)

# Mature website (2 years old)
Total Size: ~2-5 GB

Breakdown:
├── wp-admin/     15 MB  (0.5%)
├── wp-includes/  25 MB  (1%)
├── wp-content/   
│   ├── uploads/  2-4 GB (80-90%)
│   ├── plugins/  200 MB (5-8%)
│   ├── themes/   100 MB (2-4%)
│   └── cache/    50 MB  (1-2%)
└── Root files    2 MB   (0.1%)

Practice Exercise

Explore your WordPress file structure:

💻
File System Exploration
  1. Open your local WordPress installation
  2. Navigate through each main directory
  3. Find and open these files (read-only):
    • index.php - Note how simple it is
    • wp-config-sample.php - Review configuration options
    • wp-includes/version.php - Find WordPress version
    • wp-content/themes/[active-theme]/style.css - Theme information
  4. Count how many files are in wp-includes/
  5. Check the size of your uploads folder
  6. Identify which directories contain your customizations

Practice Assignment

Complete the following tasks to understand WordPress file structure:

  • Create a detailed diagram of your WordPress installation's file structure
  • List 10 core files and explain their purpose
  • Identify 5 files you should never modify and explain why
  • Find and document the purpose of 5 files in wp-includes/
  • Create a backup strategy based on the file structure
  • Write a brief report on how WordPress loads based on the file structure

Additional Resources