Re: [Docutils-users] rst2html5 title demotion?

[Guenter M. <mi...@us...>]

On 2021-05-23, Alan G. Isaac wrote:
> But of course you already did provide this option.

Actually, this was not me: the initial-header-level__ option is there
"for ages". 

__ https://docutils.sourceforge.io/docs/user/config.html#initial-header-level

> I still claim this is a bad default (who on earth is using docutils
> without CSS), but my problem is already addressed.

I changed the default value for the "html5" writer to bring it in line
with HTML5 behaviour after making it write <section> instead of <div
class="section">. Of course you should use CSS, but I believe it is a bad
idea to force everyone to define the visual features for every <Hn> level
in order to override current browser default just to keep using <H1> for
both, title and first-level section heading when the "web consensus"
moved to using <H1> for the title and <H1+n> for section headings --
independent of my personal preference in this question.


>> If I have a document with a single
>> top level header, it becomes a h1 element.

Yes, by default, a lone top-level section title is promoted to `document
title`__ (<H1 class="title">). You can, however, use the doctitle_xform__
setting if it should be a section heading instead. Then you will get a
<H1> with html4css1 and <H2> with html5.

__ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#document-title
__ https://docutils.sourceforge.io/docs/user/config.html#doctitle-xform


>> If I later include in it a document with a top level header,
>> they both become h2 elements. I have many documents like this.

This very much depends:

* If both documents use the same adornment style for their respective
  top-level headings, none will be promoted to document title.
  
* If the master document uses an adornment style that is never reused in the
  rest of the document and its children, this will become the document title 
  (<H1 class="title">) unless doctitle_xform == False.
  
It may be a good idea to check your documents for current and intended
behaviour and eventuall correct either the doctitle_xform setting or the
style of the initial heading in master documents.  

Günter