27 | 28 | Sub-heading 29 | . . . 30 | ``` 31 | 32 | Generated code: 33 | 34 | ```html 35 | . . . 36 | 37 | Main Heading 38 |

39 | Sub-heading 40 | . . . 41 | ``` 42 | 43 | By default, the first `` is styled as if it were a `

` and the second `` element is styled as if it were a `

`. 44 | 45 | ### Styling 46 | 47 | The way we style `

` to `

` elements: 48 | 49 | ```css 50 | h1 { ... } 51 | h2 { ... } 52 | ``` 53 | 54 | The `` equivalent: 55 | 56 | ```css 57 | html5-h[level="1"] { ... } /* all level 1 s */ 58 | html5-h[level="2"] { ... } /* all level 2 s */ 59 | ``` 60 | 61 | The `level` attribute (set automatically for you) allows `` to be used by people with no knowledge of [aria-level](http://www.w3.org/TR/wai-aria/states_and_properties#aria-level) (though `aria-level` can be used for this also). 62 | 63 | You can also style according to how it is nested within elements (this ties the styling to the exact document structure, rather than heading level): 64 | 65 | ```css 66 | html5-h { ... } /* level 1 */ 67 | section html5-h { ... } /* level 2 */ 68 | section section html5-h { ... } /* level 3 */ 69 | article section html5-h { ... } /* a different level 3 */ 70 | ``` 71 | 72 | ### Manually specifiying a heading level 73 | 74 | If you are using `` with HTML5 [sectioning content](https://www.w3.org/TR/html5/dom.html#sectioning-content) (as above) it is **strongly recommended to *not* manually set the `level` attribute**, as the level will be computed for you. 75 | 76 | If you do manually set the `level` attribute in your HTML (to a non-zero positive integer, e.g. "4" or "2") then the `` will take that level (and that level will be reported to Assistive Technologies (ATs)). You would need to do this when making use of `` outside of HTML5 [sectioning content](https://www.w3.org/TR/html5/dom.html#sectioning-content) (e.g. if you are using nested `

`s instead of those sectioning elements). 77 | 78 | You may also want to read our [micro-spec for how the `level` attribute behaves](https://github.com/ThePacielloGroup/html5-h/issues/16). 79 | 80 | ### Stand-alone and fallback versions 81 | 82 | We recommend using the stand-alone `` element described above, as long as: 83 | 84 | * You are using HTML5 and doing sectioning entirely with HTML5 [sectioning content](https://www.w3.org/TR/html5/dom.html#sectioning-content). 85 | * JavaScript will be available. 86 | 87 | Even if you're not using HTML5 sectioning elements exclusively, you can still use the stand-alone ``, but you'll need to set the `level` attribute manually for headings outside of HTML5 sectioning elements. (Note that you can ignore `

` elements, as they're not considered sectioning contnet the automatically-computed level will still be correct.) 88 | 89 | Alternatively, or if JavaScript may be unavailable, you should consider using the fallback version of `` that extends `

` instead. 90 | 91 | Using the fallback has the advantage that a genuine heading element will be apparent in the browser, even when JavaScript is unavailable. However, all headings will be `

`s, so accessibility wouldn't be ideal---but would be better than no headings at all. 92 | 93 | Both the stand-alone and fallback versions can be used directly from this repository. The `generate-fallback.sh` script is simply a development tool that can be run on UNIX systems to update the fallback version's code when the stand-alone code changes. 94 | 95 | There is a [demo page for the fallback version](https://thepaciellogroup.github.io/html5-h/demo-fallback.html). 96 | 97 | Development status 98 | ------------------- 99 | 100 | Currently done: 101 | 102 | * Implemented styling (heading size based on `

`/`

` nesting level). 103 | * `` elements are given `role="heading"` and a `level` and `aria-level` set to heading outline depth. 104 | 105 | To do: 106 | 107 | * Create spec document. 108 | * Tons of other things... 109 | -------------------------------------------------------------------------------- /demo-fallback.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | html5-h Fallback Demo 6 | 7 | 8 | 9 | 10 | 11 |

Ramones: Hey! Ho! Let's Go

12 |

13 |

code:

14 |

<h1 is="html5-h">Ramones: Hey! Ho! Let's Go</h1>

15 |

16 |

17 |

This page uses the fallback version of <html5-h> that extends <h1>. You need only use this version if you are not using HTML5 sectioning elements or if JavaScript may be unavailable.

18 |

If you are working entirely in HTML5 and JavaScript will be available, please use the recommended, stand-alone version of <html5-h> instead. More information can be found in the README.

19 |

20 |

Heading text level 1

21 |

Heading text level 2

22 |

Heading text level 3

23 |

Heading text level 4

24 |

Heading text level 5

25 |

Heading text level 6

26 |

27 |

28 |

29 |

30 |

31 |

32 |

code:

33 |

<h1 is="html5-h">Heading text level 1</h1>
34 | <section><h1 is="html5-h">Heading text level 2</h1>
35 |   <section><h1 is="html5-h">Heading text level 3</h1>
36 |     <section><h1 is="html5-h">Heading text level 4</h1>
37 |       <section><h1 is="html5-h">Heading text level 5</h1>
38 |         <section><h1 is="html5-h">Heading text level 6</h1>
39 |         </section>
40 |       </section>
41 |     </section>
42 |   </section>
43 | </section>

44 |

45 | 46 | 47 | -------------------------------------------------------------------------------- /demo.css: -------------------------------------------------------------------------------- 1 | section { 2 | border: 2px dashed #000099; 3 | padding: 5px; 4 | margin: 5px 5 | } 6 | 7 | section:before { 8 | content: "

"; 9 | color: #000099; 10 | } 11 | 12 | .excode { 13 | border: 1px solid black; 14 | padding-left: 1em; 15 | padding-right: 1em; 16 | } 17 | 18 | .info { 19 | border: 1px solid green; 20 | background-color: #DFD; 21 | margin: 1em 0; 22 | padding: 0 0.5em; 23 | } 24 | -------------------------------------------------------------------------------- /fallback/html5-h.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 42 | 96 | 97 | -------------------------------------------------------------------------------- /generate-fallback.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # Generate the fallback version of html5-h that extends h1 from the main version 3 | SRC=html5-h.html 4 | OUT=fallback/html5-h.html 5 | cat $SRC | \ 6 | sed 's/components\/polymer/..\/components\/polymer/' | \ 7 | sed 's/attributes="level"/attributes="level" extends="h1"/' | \ 8 | sed "/'role', 'heading'/d" \ 9 | > $OUT && \ 10 | diff -u $SRC $OUT 11 | -------------------------------------------------------------------------------- /heading-spec/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 200 | 310 | 311 | Untitled Document 312 | 313 | 314 | 315 |

The heading, h1, h2, h3, h4, h5, and h6 elements

316 |

Contexts in which this element can be used:

Where flow content is expected.

Content model:

Phrasing content.

Content attributes:

Global attributes

Tag omission in text/html:

Neither tag is omissible

Allowed ARIA role attribute values:

heading role (default - do not set), tab or presentation.

Allowed ARIA state and property attributes:

Global aria-* attributes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

336 |

interface HTMLHeadingElement : HTMLElement {};

337 |

339 |

These elements represent headings for their sections.

340 |

The semantics and meaning of these elements are defined in the section on headings and sections.

341 |

The h1–h6 elements elements have a rank given by the number in their name. The h1 element is said to have the highest rank, the h6 element has the lowest rank, and two elements with the same name have equal rank.

342 |

h1–h6 elements must not be used to markup subheadings, subtitles, alternative titles and taglines unless intended to be the heading for a new section or subsection. Instead use the markup patterns in the Common idioms without dedicated elements section of the specification.

343 |

344 |

As far as their respective document outlines (their heading and section structures) are concerned, these two snippets are semantically equivalent:

345 |

<body>  
346 | <h1>Let's call it a draw(ing surface)</h1>  
347 | <h2>Diving in</h2>  <h2>Simple shapes</h2>  
348 | <h2>Canvas coordinates</h2>  
349 | <h3>Canvas coordinates diagram</h3>  
350 | <h2>Paths</h2>  
351 | </body>

352 |

<body>   
353 | <h1>Let's call it a draw(ing surface)</h1>   
354 | <section>    <h2>Diving in</h2>   </section>   
355 | <section>    <h2>Simple shapes</h2>   </section>   
356 | <section>    <h2>Canvas coordinates</h2>    <section>     
357 | <h3>Canvas coordinates diagram</h3>    
358 | </section>   
359 | </section>   
360 | <section>    
361 | <h2>Paths</h2>   
362 | </section>  </body>

363 |

Authors might prefer the former style for its terseness, or the latter style for its convenience in the face of heavy editing; which is best is purely an issue of preferred authoring style.

364 |

365 | 366 | 367 | -------------------------------------------------------------------------------- /html5-h.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 42 | 97 | 98 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | html5-h Demo 6 | 7 | 8 | 9 | 10 | 11 | Ramones: Hey! Ho! Let's Go 12 |

13 |

code:

14 |

<html5-h>Ramones: Hey! Ho! Let's Go</html5-h>

15 |

16 |

17 |

This page uses the recommended, stand-alone version of <html5-h>. You should use this if: you are working in a HTML5 environment; all your sectioning is done via HTML5 sectioning elements and JavaScript will be available.

18 |

If any of these conditions are not met, we suggest you use the fallback version, which extends <h1> instead. More information can be found in the README.

19 |

20 | Heading text level 1 21 |

Heading text level 2 22 |

Heading text level 3 23 |

Heading text level 4 24 |

Heading text level 5 25 |

Heading text level 6 26 |

27 |

28 |

29 |

30 |

31 |

32 |

code:

33 |

<html5-h>Heading text level 1</html5-h>
34 | <section><html5-h>Heading text level 2</html5-h>
35 |   <section><html5-h>Heading text level 3</html5-h>
36 |     <section><html5-h>Heading text level 4</html5-h>
37 |       <section><html5-h>Heading text level 5</html5-h>
38 |         <section><html5-h>Heading text level 6</html5-h>
39 |         </section>
40 |       </section>
41 |     </section>
42 |   </section>
43 | </section>

44 |

45 | 46 | 47 | --------------------------------------------------------------------------------