Capabilities needed to use the Site Editor are not documented

[andronocean]

Issue Description

In the process of adding a new user role that would be able to access the Site Editor on a site using full site editing, I've discovered that there is no documentation anywhere about which capabilities are needed for such access. The Roles And Capabilities page has no references to the Site Editor or block themes at all.

The wp-admin/site-editor.php file itself contains a check for edit_theme_options, but from my testing this alone is insufficient. I created a fresh WP install, added edit_theme_options to the default Editor role, and tried to use the Site Editor. I found that:

• The Appearance item shows up in the side menu with the "Editor" item.
• Clicking it shows the editor side nav ("Design" etc), but the site preview does not load
• The Styles editor does not load
• The Pages view only loads partially (page list yes, authors are missing, previews don't work)
• Templates and Patterns views load
• 403 forbidden errors appear in network tab for some REST requests

It seems there are additional capability checks buried inside the API requests... but there's zero guidance as to what those are.

URL of the Page with the Issue

https://wordpress.org/documentation/article/roles-and-capabilities/

Section of Page with the issue

https://wordpress.org/documentation/article/roles-and-capabilities/#capabilities
https://wordpress.org/documentation/article/roles-and-capabilities/#edit_theme_options

Why is this a problem?

Without this documentation, there's no way to know how to add or modify roles to control site editor access. Many multi-user sites need to give a design or development team access to the Site Editor to change appearance. Having to make those users administrators is a security issue, since that also grants them control over users and plugins that may be risky.

Suggested Fix

At a minimum, I'd like to see the documentation for edit_theme_options (and whichever other capabilities are involved) improved to mention that they control Site Editor access when FSE is active.

A larger but better fix would be dedicated documentation (not sure where...) about how to allow or remove Site Editor access for any user role.

[github-actions]

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

[karthick-murugan]

Suggested Changes to Documentation

1. Update the edit_theme_options Capability Documentation

• The edit_theme_options capability is already documented, but it needs to explicitly mention its role in granting access to the Site Editor.
• Add the following note to the edit_theme_options section:

edit_theme_options

• Description: Allows users to edit theme options, including access to the Site Editor in Full Site Editing (FSE) environments.
• Note: While this capability grants access to the Site Editor, additional capabilities may be required for full functionality. For example, users may also need edit_posts, edit_pages, and edit_others_posts to fully utilize the Site Editor's features.

2. Add a New Section for Site Editor Capabilities

• Create a new section dedicated to the Site Editor in the Roles and Capabilities documentation.
• Include a table listing all the capabilities required for different aspects of the Site Editor.

Site Editor Capabilities

The Site Editor in Full Site Editing (FSE) environments requires the following capabilities for full functionality:

Capability	Description
edit_theme_options	Grants access to the Site Editor and its navigation menu.
edit_posts	Allows users to edit posts, which is required for managing templates.
edit_pages	Allows users to edit pages, which is required for managing page templates.
edit_others_posts	Allows users to edit others' posts, which is required for managing templates.
read	Allows users to view the site, which is required for previewing changes.
upload_files	Allows users to upload media, which is required for adding images and media.

3. Provide Examples for Custom Roles

Include examples of how to create custom roles with access to the Site Editor using the add_role() and add_cap() functions.

function add_site_editor_role() {
    add_role(
        'site_editor',
        __( 'Site Editor' ),
        array(
            'edit_theme_options' => true,
            'edit_posts'         => true,
            'edit_pages'         => true,
            'edit_others_posts'  => true,
            'read'               => true,
            'upload_files'       => true,
        )
    );
}
add_action( 'init', 'add_site_editor_role' );

4. Explain REST API Capability Checks

Mention that some REST API endpoints used by the Site Editor may require additional capabilities, such as edit_posts or edit_pages, to function properly.

Provide guidance on debugging REST API errors related to insufficient capabilities.

REST API Capability Checks

The Site Editor relies on REST API endpoints to load data and preview changes. If users encounter 403 Forbidden errors, ensure they have the following capabilities:

• edit_posts
• edit_pages
• edit_others_posts