Update theme extensibility documentation to include editor widths #6531
Conversation
This updates the extensibility document, and adds a section around loading editor styles. It gives examples for how to change the colors of the editor (which will look good once #6406 gets merged), as well as how to change the width of the editor. The last part fixes #1483. CC: @maddisondesigns
|
Is there anything we can do with these long nesting CSS Other than that +1 for updating the docs. |
Long term, yes, the goal is to continue to polish and refactor so that ideally you don't have to write a separate editor stylesheet at all, but we can load the theme stylesheet in directly. This is a north star, but is also somewhat utopian. Nonetheless sort of an umbrella goal is to make it as easy as possible for the theme developer. We're not there yet, though, and in order for you to be able to style the theme width, you have to add some specificity to the selector so it overrides the base styles. However I did manage to simplify it a little bit: Also added the default block appender there, which I'd missed previously. Further interim improvements can probably come as part of #5360. |
docs/extensibility/theme-support.md
Outdated
| @@ -91,3 +91,69 @@ add_theme_support( 'disable-custom-colors' ); | |||
| ``` | |||
|
|
|||
| This flag will make sure users are only able to choose colors from the `editor-color-palette` the theme provided or from the editor default colors if the theme did not provide one. | |||
|
|
|||
|
|
|||
There was a problem hiding this comment.
Are the extra spaces between sections necessary? Maybe we should remove them in a effort to be consistent with the rest of the docs
There was a problem hiding this comment.
Ack, those are from my markdown editor. I'll clean it up in a normal text editor before I merge. Thanks!
|
|
||
| ### Basic colors | ||
|
|
||
| You can style the editor like any other webpage. Here's an example for how to change the background color and the font color. Paste this in your `style-editor.css `file: |
There was a problem hiding this comment.
Nitpick but the style-editor.css section has the space inside the backtick when it should come after.
There was a problem hiding this comment.
Also the second sentence could be more direct:
Here's how to change the background color and the font color to blue:
|
|
||
| ### Add the stylesheet | ||
|
|
||
| First thing you need to do is to enqueue the new editor style. Like this: |
There was a problem hiding this comment.
This is missing an article and the next sentence is a fragment. It might read better as:
The first thing to do is enqueue the new editor style:
```
/**
* Enqueue block editor style
*/
function mytheme_block_editor_styles() {
wp_enqueue_style( 'mytheme-block-editor-styles', get_theme_file_uri( '/style-editor.css' ), false, '1.0', 'all' );
}
add_action( 'enqueue_block_editor_assets', 'mytheme_block_editor_styles' );
```
| add_action( 'enqueue_block_editor_assets', 'mytheme_block_editor_styles' ); | ||
| ``` | ||
|
|
||
| Now create a new stylesheet, `style-editor.css` and save it in your theme directory. |
There was a problem hiding this comment.
"Now" is a strange word here, this might read better without:
Create a new stylesheet, `style-editor.css`, in your theme directory.
| } | ||
| ``` | ||
|
|
||
| This will make your editor use blue shades. |
There was a problem hiding this comment.
This could be removed as it adds nothing for anyone who knows CSS already, especially if the above changes were made that reference the colour first.
|
|
||
| ### Changing the width of the editor | ||
|
|
||
| If you'd like to change the main column width of the editor, you can add the following to your `style-editor.css` file: |
There was a problem hiding this comment.
"If you'd like " just clutters up the sentence here so it could be removed; trimming this down to:
To change the main column width of the editor, add the following CSS to `style-editor.css`:
|
|
||
| ## Editor styles | ||
|
|
||
| A theme can provide a stylesheet to the editor itself, to change colors, fonts, and any aspect of the editor. |
There was a problem hiding this comment.
The comma usage here confused me, I think the first one is a semicolon really. How about:
A theme can provide a stylesheet that will style the editor. You can use this to change colors, fonts, and any other visual aspect of the editor.
|
It would make sense to just introduce a It could be enhanced to support an array of options: Likewise with the background/text colours: |
|
Having just read the latest update to #6406 I would actually encourage to go with something like I've suggested above. You could then use get_theme_support( 'editor-color' ) to fetch the background colour, and then use PHP to determine if the background colour is dark and then apply |
👍 👍 thank you.
I don't disagree, but I think it's a gray-area. The fact that you can change these things with CSS gives you more freedom to make the editor match your specific theme itself, where explicit PHP functions slightly handcuff you. For example maybe you'd like to have a post title that's much wider than the body text, or perhaps you're not using a flat background color but a gradient or a background image. That's not a blanket statement that you don't have a point, you absolutely do, and it falls into that whole area that we should definitely make this easier for the themer than it is today, and suggestions like yours could pave the way towards that. I'd probably thumb up a PR, for example. |
Adding my suggestion wouldn't handcuff things in anyway though. You can still apply styles like in your documentation example, even with such an If I build a site with those styles applied, and at some point in the future Gutenberg (or WordPress 5.0+ at that point) adds some new UI which also requires the width being set, the site would require a manual update in order for that width to line up with everything else. It's very common that sites (especially smaller low budget ones) are one and done for agencies when built (outside of WP & plugin updates), where you cannot dedicate the time/resources to go in and update styles like this for each and every site. Just playing devils advocate really. |
|
If my suggestion is something which would be considered though, do let me know and I can whip up a PR when I have time. |
I personally think it does make sense. I'd love for such a PR, feel free to CC me. @youknowriad would you have any concerns with such functions file additions? |
|
Yes, this looks like a reasonable addition but I have some concerns:
I feel like it can be introduced at anytime and we may want to wait a bit to see what themes do with Gutenberg before committing to an API. |
|
Forgive me if this is not the best place to ask, but is there any way to detect the current page/post classes in Gutenberg? It would be nice to have the front-end body classes available somewhere in Gutenberg's structure, like we had in the classic editor, so we could adjust the CSS to different page templates. Edit: added this suggestion to the main issue discussion. |
Improve theme extensibility docs with copy edits; simplify changes made in #6531.
Improve theme extensibility docs with copy edits; simplify changes made in #6531.
This updates the extensibility document, and adds a section around loading editor styles. It gives examples for how to change the colors of the editor (which will look good once #6406 gets merged), as well as how to change the width of the editor. The last part fixes #1483.
CC: @maddisondesigns