@@ -229,16 +229,20 @@ Registering Custom Highlights</h3>
229
229
The <dfn>custom highlight name</dfn> assigned to a [=custom highlight=] when it is [=registered=]
230
230
is used to identify the highlight during styling (see [[#styling-highlights]] ).
231
231
232
- Note: When registering a [=custom highlight=] , authors are advised to use a
233
- [=custom highlight name=] that is a valid CSS [=identifier=] . Using a name that is not a valid
234
- identifier can make the highlight hard, and in some cases impossible, to style via CSS.
232
+ Note: When registering a [=custom highlight=] ,
233
+ authors are advised to use a [=custom highlight name=] that is a valid CSS [=identifier=] .
234
+ Using a name that is not a valid identifier can make the highlight hard,
235
+ and in some cases impossible, to style via CSS.
235
236
236
237
Note: It is possible to [=register=] a [=custom highlight=] with more than one [=custom highlight name=] .
237
- However, using more than one name to style a highlight will assign the highlight multiple different sets
238
- of styles, without a way to control the stacking order of conflicting styles within these sets
239
- during [[#painting|painting]] . This could be limiting for authors and could cause confusing painting behavior
240
- (see the <a href="#styling-problems-with-multiple-names-per-highlight">example</a> below for more context). Therefore,
241
- <b> authors are advised to only use one name per highlight during styling</b> .
238
+ However, using more than one name to style a highlight
239
+ will assign the highlight multiple different sets of styles,
240
+ without a way to control the stacking order of conflicting styles
241
+ within these sets during [[#painting|painting]] .
242
+ This could be limiting for authors and could cause confusing painting behavior
243
+ (see the <a href="#styling-problems-with-multiple-names-per-highlight">example</a> below for more context).
244
+ Therefore, <b> authors are advised to only use one name per highlight during styling</b> .
245
+
242
246
<div class=example id=styling-problems-with-multiple-names-per-highlight>
243
247
<xmp highlight=html>
244
248
<style>
@@ -260,12 +264,18 @@ Registering Custom Highlights</h3>
260
264
CSS.highlights.set('bar' , h);
261
265
</script>
262
266
</xmp>
263
- In the example above, the same [=custom highlight=] object is [=registered=] under the names 'foo' and 'bar' .
264
- Since each of the [=style rules=] target the same highlight and have the same [=specificity=] , authors might
265
- expect the last rule to win in cascading order and the highlighted content to be green. However, each highlight
266
- name gets an independent set of highlight styles, and the highlight will be painted once per name. In
267
- this case, because 'foo' was registered before 'bar' , the highlight will be first painted with 'foo' 's
268
- color (green) and then with 'bar' 's color (red). As a result, the highlighted content will appear red.
267
+
268
+ In the example above,
269
+ the same [=custom highlight=] object is [=registered=] under the names 'foo' and 'bar' .
270
+ Since each of the [=style rules=] target the same highlight and have the same [=specificity=] ,
271
+ authors might expect the last rule to win in cascading order
272
+ and the highlighted content to be green.
273
+ However, each highlight name gets an independent set of highlight styles,
274
+ and the highlight will be painted once per name.
275
+ In this case, because 'foo' was registered before 'bar' ,
276
+ the highlight will be first painted with 'foo' 's color (green)
277
+ and then with 'bar' 's color (red).
278
+ As a result, the highlighted content will appear red.
269
279
</div>
270
280
271
281
<h2 id=styling-highlights>
0 commit comments