Theme Handbook Overhaul (Tracking Ticket)

[justintadlock]

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
  • Templates
  • The Loop
  • [Theme Handbook Overhaul] Classic Themes > 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

[github-actions]

Heads up @kafleg @carolinan @TeBenachi - the "themes" label was applied to this issue.

[zzap]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.

[javiercasares]

I'm going to add me more work here :P but... do you need help to have this handbook like the plugin one on GitHub? There is a ticket pending to move it to the WordPress organization, but we should create this documentation as Markdown.

I can help move it from Google Docs to a GitHub repo if it works for you.

[justintadlock]

@javiercasares - I'd love to have a dedicated GitHub repo for managing this. It would save a lot of headaches with moving content around. It's something @richtabor and I recently discussed that would help contributors keep things updated.

I'm personally fine helping to move the content over to Markdown in a repo, and we can certainly start drafting upcoming docs in Markdown.

CC: @kafleg, @carolinan - Thoughts?

[javiercasares]

We've been working on this with @zzap for some projects (The Advanced Administration, a year ago, the Plugins with the plugins team a couple of months ago -working on finishing the transition-), so, it's a good opportunity to plan it.

There are 2 good things behind this:

• autosync with the developer site (everything in the "main" will be synced automatically every 15 minutes
• start working on the internationalization project, so we can have all the documentation in a lot of languages.

[justintadlock]

@javiercasares - You mentioned a pending ticket. Can you share that link? That'd probably be the best place to discuss anything we need to do on our end. And I can update the instructions in this ticket for drafting new docs when this moves forward.

For existing Google Docs, there's not many that would need to be moved to Markdown. It's just the open tickets above (under the Classic Themes and Advanced Topics sections). All of the other closed tickets have now been moved to develop.wordpress.org/themes.

[javiercasares]

• DevHub Plugins Team (developer.wordpress.org/plugins) Handbook sync
• Plugins Team (make.wordpress.org/plugins) Handbook sync