Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify the wp-block-styles documentation #23359

Merged
merged 6 commits into from Jun 23, 2020
Merged

Clarify the wp-block-styles documentation #23359

merged 6 commits into from Jun 23, 2020

Conversation

@kjellr
Copy link
Contributor

kjellr commented Jun 22, 2020

This PR adds some clarification to the wp-block-styles documentation.

Previously, it stated:

Core blocks include default styles. The styles are enqueued for editing but are not enqueued for viewing unless the theme opts-in to the core styles. If you’d like to use default styles in your theme, add theme support for wp-block-styles

This is misleading, since what most folks would consider "default" styles (from style.css) are enqueued by default. The opt-in actually applies only to the more opinionated styles in theme.css. This PR makes that distinction more clear:

Core blocks include default structural styles. These are loaded in both the editor and the front end by default. An example of these styles is the CSS that powers the columns block. Without these rules, the block would break entirely on the front end.

The block editor allows themes to opt-in to slightly more opinionated styles for the front end. An example of these styles is the default color bar to the left of blockquotes. If you'd like to use these opinionated styles in your theme, add theme support for wp-block-styles

kjellr added 3 commits Jun 22, 2020
@github-actions
Copy link

github-actions bot commented Jun 22, 2020

Size Change: 0 B

Total Size: 1.13 MB

ℹ️ View Unchanged
Filename Size Change
build/a11y/index.js 1.14 kB 0 B
build/annotations/index.js 3.62 kB 0 B
build/api-fetch/index.js 3.4 kB 0 B
build/autop/index.js 2.82 kB 0 B
build/blob/index.js 620 B 0 B
build/block-directory/index.js 7.27 kB 0 B
build/block-directory/style-rtl.css 937 B 0 B
build/block-directory/style.css 937 B 0 B
build/block-editor/index.js 107 kB 0 B
build/block-editor/style-rtl.css 10.6 kB 0 B
build/block-editor/style.css 10.6 kB 0 B
build/block-library/editor-rtl.css 7.6 kB 0 B
build/block-library/editor.css 7.6 kB 0 B
build/block-library/index.js 129 kB 0 B
build/block-library/style-rtl.css 8.03 kB 0 B
build/block-library/style.css 8.04 kB 0 B
build/block-library/theme-rtl.css 730 B 0 B
build/block-library/theme.css 732 B 0 B
build/block-serialization-default-parser/index.js 1.88 kB 0 B
build/block-serialization-spec-parser/index.js 3.1 kB 0 B
build/blocks/index.js 48.2 kB 0 B
build/components/index.js 197 kB 0 B
build/components/style-rtl.css 15.8 kB 0 B
build/components/style.css 15.8 kB 0 B
build/compose/index.js 9.62 kB 0 B
build/core-data/index.js 11.4 kB 0 B
build/data-controls/index.js 1.29 kB 0 B
build/data/index.js 8.44 kB 0 B
build/date/index.js 5.47 kB 0 B
build/deprecated/index.js 772 B 0 B
build/dom-ready/index.js 569 B 0 B
build/dom/index.js 3.19 kB 0 B
build/edit-navigation/index.js 9.64 kB 0 B
build/edit-navigation/style-rtl.css 1.02 kB 0 B
build/edit-navigation/style.css 1.02 kB 0 B
build/edit-post/index.js 303 kB 0 B
build/edit-post/style-rtl.css 5.48 kB 0 B
build/edit-post/style.css 5.47 kB 0 B
build/edit-site/index.js 16.6 kB 0 B
build/edit-site/style-rtl.css 3.02 kB 0 B
build/edit-site/style.css 3.02 kB 0 B
build/edit-widgets/index.js 9.33 kB 0 B
build/edit-widgets/style-rtl.css 2.42 kB 0 B
build/edit-widgets/style.css 2.42 kB 0 B
build/editor/editor-styles-rtl.css 537 B 0 B
build/editor/editor-styles.css 539 B 0 B
build/editor/index.js 44.9 kB 0 B
build/editor/style-rtl.css 3.81 kB 0 B
build/editor/style.css 3.81 kB 0 B
build/element/index.js 4.65 kB 0 B
build/escape-html/index.js 733 B 0 B
build/format-library/index.js 7.72 kB 0 B
build/format-library/style-rtl.css 547 B 0 B
build/format-library/style.css 548 B 0 B
build/hooks/index.js 2.13 kB 0 B
build/html-entities/index.js 622 B 0 B
build/i18n/index.js 3.56 kB 0 B
build/is-shallow-equal/index.js 710 B 0 B
build/keyboard-shortcuts/index.js 2.51 kB 0 B
build/keycodes/index.js 1.94 kB 0 B
build/list-reusable-blocks/index.js 3.13 kB 0 B
build/list-reusable-blocks/style-rtl.css 450 B 0 B
build/list-reusable-blocks/style.css 451 B 0 B
build/media-utils/index.js 5.29 kB 0 B
build/notices/index.js 1.79 kB 0 B
build/nux/index.js 3.4 kB 0 B
build/nux/style-rtl.css 663 B 0 B
build/nux/style.css 660 B 0 B
build/plugins/index.js 2.56 kB 0 B
build/primitives/index.js 1.5 kB 0 B
build/priority-queue/index.js 789 B 0 B
build/redux-routine/index.js 2.85 kB 0 B
build/rich-text/index.js 14 kB 0 B
build/server-side-render/index.js 2.67 kB 0 B
build/shortcode/index.js 1.7 kB 0 B
build/token-list/index.js 1.27 kB 0 B
build/url/index.js 4.06 kB 0 B
build/viewport/index.js 1.85 kB 0 B
build/warning/index.js 1.14 kB 0 B
build/wordcount/index.js 1.17 kB 0 B

compressed-size-action

Copy link
Contributor

jasmussen left a comment

Beautiful improvement.

Stumbled briefly on this one:

Without these rules, the block would break entirely on the front end.

Break how? If you read this quickly you might simply assume you see a table with borders, but in fact you'd see all your blocks in a single column as if they were not in any columns block at all. Fundamentally the columns block is probably good to highlight because it is profoundly useless without them. But I wonder if we can dramatize and clarify at the same time:

Without these rules, the block would break entirely on the front end, with a broken layout and no columns to find at all.

@kjellr
Copy link
Contributor Author

kjellr commented Jun 22, 2020

Without these rules, the block would break entirely on the front end, with a broken layout and no columns to find at all.

Good suggestion! I think I can simplify that a little bit to:

Without these rules, the block would result in a broken layout containing no columns at all.

kjellr added 2 commits Jun 22, 2020
@kjellr
Copy link
Contributor Author

kjellr commented Jun 23, 2020

(Just trying to get these tests to pass... They keep throwing errors. 😕)

@jasmussen
Copy link
Contributor

jasmussen commented Jun 23, 2020

Isn't there a docs command line change you need to run? The failure could be legitimate. I'll defer to @mkaz on that

@kjellr
Copy link
Contributor Author

kjellr commented Jun 23, 2020

I think that shouldn't be necessary here since I'm just changing some existing text. But I'll take a closer look once these tests finish running.

@jasmussen
Copy link
Contributor

jasmussen commented Jun 23, 2020

They've failed a ton lately, and often pass with two or three restarts.

@kjellr kjellr merged commit f184452 into master Jun 23, 2020
4 checks passed
4 checks passed
build build
Details
build
Details
pull-request-automation
Details
Travis CI - Pull Request Build Passed
Details
@kjellr kjellr deleted the update/block-styles-docs branch Jun 23, 2020
@github-actions github-actions bot added this to the Gutenberg 8.5 milestone Jun 23, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

2 participants
You can’t perform that action at this time.