Add a 410 template for removed lessons, courses and tutorials

[muneeb-ashraf]

Fixes #2914.

What

Retired content on Learn is set to draft (or trashed) rather than deleted, as described in #2496. Its URLs currently return a 404, which tells search engines the page might come back. This sends a 410 Gone instead, with a dedicated template.

• functions.php: a 404_template_hierarchy filter. When a 404 request names a draft or trashed course, lesson, lesson-plan or wporg_workshop (tutorial) post, it sends status_header( 410 ) and puts the 410 template first. Trashed posts are matched through their __trashed slug suffix.
• templates/410.html + patterns/410-page-content.php: the 404 layout with a "This content is no longer available." heading, the search block, and the line suggested in the issue: "If you were looking for something specific, please let us know", linking to /report-content-feedback/.

Nothing changes for published content, URLs that never existed, private posts, or other post types. Existing redirects in wporg_learn_redirect_old_urls() still run first, since they fire on template_redirect, before the template is chosen.

The wording is a first pass based on the suggestion in the issue. I'm happy to change it.

Testing

I tested the two new functions against WordPress trunk with a throwaway PHPUnit harness. It pulls them out of functions.php and registers the post types with Learn's rewrite slugs:

Request	Content state	Template hierarchy
/tutorial/old-tutorial/	draft wporg_workshop	410, 404
/lesson/old-lesson/	trashed lesson	410, 404
/course/old-course/	draft course	410, 404
/lesson/never-existed/	none	404
/lesson/private-lesson/	private lesson	404
/old-post/	draft post	404
/lesson/live-lesson/	published	not a 404

Without the filter, the first three cases fail and the rest still pass. PHPCS passes on the changed files with the repo's ruleset.

To check after deploy: curl -sI on the URL of any drafted tutorial should return HTTP/2 410.

AI assistance

• AI assistance: Yes
• Tool: Claude Code
• Model: Claude Opus 5.5
• Used for: Code and tests. I reviewed the change and ran the tests.

🤖 Generated with Claude Code

https://claude.ai/code/session_01W6LxjEQnP4PPgXXvAM3M2F