Here's the question in full:
I have this text:
Heading 1 ========= All my life, I wanted to be H1. Heading 1.1 ----------- But along came H1, and so shouldn't I be H2? No! I'm H1! Heading 1.1.1 ************* Yeah, imagine me, I'm stuck at H3! No?!?When I run it through tools/html.py, I get unexpected results (below). I was expecting H1, H2, then H3; instead, I get H1, H1, H2:
... <html lang="en"> <head> ... <title>Heading 1</title> <link rel="stylesheet" href="default.css" type="text/css" /> </head> <body> <div class="document" id="heading-1"> <h1 class="title">Heading 1</h1> <-- first H1 <p>All my life, I wanted to be H1.</p> <div class="section" id="heading-1-1"> <h1><a name="heading-1-1">Heading 1.1</a></h1> <-- H1 <p>But along came H1, and so now I must be H2.</p> <div class="section" id="heading-1-1-1"> <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2> <p>Yeah, imagine me, I'm stuck at H3!</p> ...What gives?
Check the "class" attribute on the H1 tags, and you will see a difference. The first H1 is actually <h1 class="title">; this is the document title, and the default stylesheet renders it centered. There can also be an <h2 class="subtitle"> for the document subtitle.
If there's only one highest-level section title at the beginning of a document, it is treated specially, as the document title. (Similarly, a lone second-highest-level section title may become the document subtitle.) Rather than use a plain H1 for that, we use <h1 class="title"> so that we can use H1 again within the document. Why do we do this? HTML only has H1-H6, so by making H1 do double duty, we effectively reserve these tags to provide 6 levels of heading beyond the single document title.
HTML is being used for dumb formatting for nothing but final display. A stylesheet is required, and one is provided: tools/stylesheets/default.css. Of course, you're welcome to roll your own. The default stylesheet provides rules to format <h1 class="title"> and <h2 class="subtitle"> differently from ordinary <h1> and <h2>:
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
(Thanks to Mark McEahern for the question and much of the answer.)