Hướng dẫn chi tiết cấu trúc thư mục theme WordPress

Nếu bạn đang bắt đầu tự xây dựng hoặc chỉnh sửa theme WordPress, điều đầu tiên cần nắm là các file trong một theme được tổ chức theo quy tắc nhất định — không phải ngẫu nhiên. Hiểu đúng cấu trúc này sẽ giúp bạn biết cần sửa file nào, đặt code ở đâu và tại sao WordPress lại hiển thị giao diện theo cách đó.

Theme WordPress được lưu ở đâu?

Tất cả theme cài trên WordPress đều nằm trong thư mục wp-content/themes/. Mỗi theme là một thư mục con bên trong đó. Dù bạn có cài bao nhiêu theme, WordPress chỉ cho phép một theme hoạt động tại một thời điểm. Cơ chế tách biệt này đảm bảo việc cập nhật lõi WordPress không ảnh hưởng đến giao diện bạn đang dùng.

File tối thiểu để WordPress nhận diện một theme

Một theme hợp lệ chỉ cần đúng hai file: style.css và index.php. Thiếu một trong hai, theme sẽ không hiển thị trong trang quản trị.

File style.css

Ngoài việc chứa CSS, file này còn có nhiệm vụ khai báo thông tin nhận dạng của theme thông qua phần comment ở đầu file. WordPress đọc phần này để lấy tên, mô tả và phiên bản theme. Ví dụ khai báo chuẩn:

/*
Theme Name: Tên Theme
Theme URI: https://example.com
Author: Tên Tác Giả
Author URI: https://example.com
Description: Mô tả ngắn về theme
Version: 1.0.0
Text Domain: ten-theme
*/

File index.php

Đây là file template dự phòng cuối cùng. Khi WordPress không tìm thấy file template phù hợp với loại trang đang được truy cập, nó sẽ tự động dùng index.php để hiển thị nội dung. File này bắt buộc phải có trong mọi theme.

Cấu trúc thư mục theme WordPress đầy đủ

Dưới đây là sơ đồ tổ chức file của một theme được xây dựng theo tiêu chuẩn thực tế:

ten-theme/
│
├── style.css               → Khai báo theme + CSS chính
├── index.php               → Template fallback (bắt buộc)
├── functions.php           → Đăng ký tính năng, load script/style
├── screenshot.png          → Ảnh preview trong trang Appearance (1200x900px)
│
├── header.php              → Phần header: logo, menu điều hướng
├── footer.php              → Phần footer: copyright, widget dưới
├── sidebar.php             → Cột bên (nếu layout có sidebar)
│
├── single.php              → Trang chi tiết bài viết
├── page.php                → Trang tĩnh (About, Contact...)
├── archive.php             → Trang lưu trữ theo tag, ngày, tác giả
├── category.php            → Trang danh sách bài viết theo chuyên mục
├── search.php              → Trang kết quả tìm kiếm
├── 404.php                 → Trang lỗi không tìm thấy
│
├── css/                    → File CSS bổ sung
├── js/                     → File JavaScript
├── images/                 → Hình ảnh tĩnh của theme
└── inc/                    → Các file PHP hỗ trợ, helper function

Chức năng từng file template

• functions.php là trung tâm điều khiển của theme. Đây là nơi bạn đăng ký menu, widget, load CSS/JS qua wp_enqueue_scripts, khai báo các tính năng hỗ trợ như thumbnail, breadcrumb và viết các hàm dùng chung toàn theme.
• header.php và footer.php chứa HTML được dùng lại trên tất cả trang. Gọi chúng trong các file template khác bằng get_header() và get_footer(). Tương tự, sidebar.php được gọi bằng get_sidebar().
• single.php xử lý trang đọc bài viết blog.
• page.php dành cho các trang tĩnh.
• archive.php hiển thị danh sách bài viết khi lọc theo tag, ngày hoặc tác giả.
• search.php trả về kết quả tìm kiếm.
• 404.php hiển thị thông báo khi URL không tồn tại.
• category.php dành riêng cho trang danh sách bài viết theo chuyên mục. Bạn còn có thể tạo file riêng cho từng chuyên mục theo định dạng category-{slug}.php — ví dụ category-tin-tuc.php để tùy biến giao diện riêng cho chuyên mục tin tức.

Template Hierarchy — Quy tắc ưu tiên file

WordPress không chọn file template ngẫu nhiên. Với mỗi loại trang, hệ thống tìm kiếm file theo thứ tự từ cụ thể đến tổng quát. File đầu tiên tìm được sẽ được dùng. Nếu không có file nào khớp, WordPress dùng index.php.

Ví dụ: người dùng truy cập chuyên mục có slug tin-tuc, WordPress sẽ tìm lần lượt: category-tin-tuc.php → category-[id].php → category.php → archive.php → index.php. File nào tồn tại đầu tiên trong danh sách đó sẽ được sử dụng.

Hiểu đúng cơ chế này giúp bạn biết chính xác cần tạo file nào để tùy biến giao diện cho từng loại trang mà không cần chỉnh sửa file khác.

Template Parts — Tái sử dụng code

Thay vì viết lặp HTML ở nhiều file, bạn tách ra thành các đoạn nhỏ (template parts) và nhúng vào bằng hàm get_template_part(). Thông thường các file này được đặt trong thư mục template-parts/. Ví dụ: template-parts/content.php chứa HTML hiển thị thông tin bài viết, có thể dùng chung trong cả single.php lẫn archive.php.

Quy tắc đặt tên file cho Custom Post Type và Custom Taxonomy

Khi website có loại nội dung tùy chỉnh như sản phẩm, dự án, bất động sản… bạn cần thêm các file template theo đúng quy tắc đặt tên để WordPress tự động nhận diện:

Đặt tên đúng quy tắc thì WordPress tự khớp template với dữ liệu — không cần viết thêm logic xử lý URL hay redirect nào cả.

Tại sao cần chuẩn hóa cấu trúc theme?

Theme được tổ chức rõ ràng giúp WordPress xác định file cần load nhanh hơn, giảm thời gian xử lý phía server. Về mặt bảo trì, khi cần debug hay bàn giao dự án, developer khác có thể đọc hiểu codebase ngay mà không mất thời gian dò tìm. Đây cũng là điều kiện bắt buộc nếu bạn muốn submit theme lên WordPress.org.

Tài liệu tham khảo chính thức về Template Hierarchy: WordPress Developer Handbook.

Kết luận

Cấu trúc thư mục theme WordPress được thiết kế có hệ thống, không phải tự phát. Hai file bắt buộc là style.css và index.php. Các file còn lại phục vụ từng loại trang cụ thể theo cơ chế Template Hierarchy. Nắm chắc phần này sẽ giúp bạn tự tin hơn trong quá trình lập trình và tùy biến giao diện theo ý muốn.