In April, there was a proposal to overhaul the WordPress Theme Handbook with a new structure and learning pathways for theme creators. April 28 was the deadline for feedback on the proposal. After two meetings and an open discussion, we have an outline that we can begin working from.

To reference the progress on this project, visit the following docs and posts:

• Handbook Outline (Google Doc)
• Theme Handbook Overhaul Proposal
• Themes Team Meeting Notes (April 11, 2023)

Tracking Issues

This is an overall tracking ticket for the project. The following list should be updated to link to specific tickets as they are created. The list may also be amended as this project progresses. Note that some pages already exist and merely need to be moved or potentially updated.

• Welcome to the Theme Handbook
• Chapter 1: Getting Started
  • [Theme Handbook Overhaul] Getting Started > Chapter Landing Page #1257
  • [Theme Handbook Overhaul] Getting Started > What is a theme? #841
  • [Theme Handbook Overhaul] Getting Started > Who is this handbook for? #845
  • [Theme Handbook Overhaul] Getting Started > Reading this handbook #847
  • [Theme Handbook Overhaul] Getting Started > Tools and setup #852
  • [Theme Handbook Overhaul] Getting Started > Quick-start guide #878
• Chapter 2: Core Concepts
  • [Theme Handbook Overhaul] Core Concepts > Chapter Landing Page #1258
  • [Theme Handbook Overhaul] Core Concepts > Theme Structure #920
  • [Theme Handbook Overhaul] Core Concepts > Main Stylesheet #921
  • [Theme Handbook Overhaul] Core Concepts > Templates #930
  • [Theme Handbook Overhaul] Core Concepts > Custom Functionality #969
  • [Theme Handbook Overhaul] Core Concepts > Including Assets #984
  • [Theme Handbook Overhaul] Core Concepts > Global Settings and Styles #989
  • Tools and resources
• Chapter 3: Global Settings and Styles
  • [Theme Handbook Overhaul] Global Settings and Styles > Chapter Landing Page #1123
  • [Theme Handbook Overhaul] Global Settings and Styles > Introduction to theme.json #1122
  • [Theme Handbook Overhaul] Global Settings and Styles > Settings #1003
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Appearance Tools #1084
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Border #1049
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Color #1050
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Custom #1061
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Dimensions #1066
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Layout #1078
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Lightbox #1121
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Position #1099
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Shadow #1092
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Spacing #1093
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Typography #1108
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Use Root Padding Aware Alignments #1098
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Blocks #1111
    • [Theme Handbook Overhaul] Global Settings and Styles > Settings > Settings Reference #987
  • [Theme Handbook Overhaul] Global Settings and Styles > Styles #1117
    • [Theme Handbook Overhaul] Global Settings and Styles > Styles > Applying Styles #1118
    • [Theme Handbook Overhaul] Global Settings and Styles > Styles > Using Presets #1119
    • [Theme Handbook Overhaul] Global Settings and Styles > Styles > Styles Reference #1120
  • [Theme Handbook Overhaul] Global Settings and Styles > Custom Templates #1113
  • [Theme Handbook Overhaul] Global Settings and Styles > Patterns #1124
  • [Theme Handbook Overhaul] Global Settings and Styles > Template Parts #1116
  • [Theme Handbook Overhaul] Global Settings and Styles > Style Variations #1112
• Chapter 4: Templates
  • [Theme Handbook Overhaul] Templates > Chapter Landing Page #1125
  • [Theme Handbook Overhaul] Templates > Introduction to templates #1126
  • [Theme Handbook Overhaul] Templates > Templates #1128
  • [Theme Handbook Overhaul] Templates > Template Hierarchy #1132
  • [Theme Handbook Overhaul] Templates > Template Parts #1130
• Chapter 5: Patterns
  • [Theme Handbook Overhaul] Patterns > Chapter Landing Page #1519
  • [Theme Handbook Overhaul] Patterns > Introduction to Patterns #1478
  • [Theme Handbook Overhaul] Patterns > Registering Patterns #1479
  • [Theme Handbook Overhaul] Patterns > Using PHP in Patterns #1480
  • [Theme Handbook Overhaul] Patterns > Usage in Templates #1483
  • [Theme Handbook Overhaul] Patterns > Starter Patterns #1486
  • [Theme Handbook Overhaul] Patterns > Block Type Patterns #1505
  • [Theme Handbook Overhaul] Patterns > Locking Blocks in Patterns #1518
• Chapter 6: Features
  • [Theme Handbook Overhaul] Features > Chapter Landing Page #1134
  • [Theme Handbook Overhaul] Features > Block Patterns #1141
  • [Theme Handbook Overhaul] Features > Block Style Variations #1138
  • [Theme Handbook Overhaul] Features > Block Stylesheets #1135
  • [Theme Handbook Overhaul] Features > Block Variations #1142
• Chapter 7: Classic Themes
  • Chapter Landing Page
  • [Theme Handbook Overhaul] Classic Themes > Your First Theme #1357
  • [Theme Handbook Overhaul] Classic Themes > Basics > Templates #1685
  • [Theme Handbook Overhaul] Classic Themes > Basics > The Loop #1684
  • [Theme Handbook Overhaul] Classic Themes > Basics > Template Tags #1358
  • Conditional tags
  • Theme functionality
  • Theme options / the Customizer
  • Plugin API hooks
• Chapter 8: Advanced Topics
  • [Theme Handbook Overhaul] Advanced Topics > Chapter Landing Page #1417
  • [Theme Handbook Overhaul] Advanced Topics > Internationalization #1383
  • [Theme Handbook Overhaul] Advanced Topics > Child Themes #1404
  • [Theme Handbook Overhaul] Advanced Topics > Build Process #1377
  • [Theme Handbook Overhaul] Advanced Topics > Privacy #1361
  • [Theme Handbook Overhaul] Advanced Topics > Testing #1412
  • [Theme Handbook Overhaul] Advanced Topics > Debugging #1370
  • [Theme Handbook Overhaul] Advanced Topics > Security #1359
  • [Theme Handbook Overhaul] Advanced Topics > Publishing Themes #1409
• Chapter 9: Accessibility
  • Chapter Landing Page
  • Principles of accessibility
  • Block themes
  • Resources
• Chapter 10: Guides
  • Chapter Landing Page
  • Building With Create Block Theme
  • Migrating a classic theme to blocks
  • [Theme Handbook Overhaul] Guides > UI Best Practices #1419
  • [Theme Handbook Overhaul] Guides > JavaScript Best Practices #1418
• Contributing