Re: [Docutils-users] forcing heading levels

[Matthew W. <mwo...@gm...>]

On 2014-01-10 15:03, David Goodger wrote:
> On 10 January 2014 13:46, Matthew Woehlke wrote:
>> I have a really simple document like:
>>
>> Title
>> =====
>>
>> Section
>> -------
>>
>> ...text here...
>>
>> Section
>> -------
>>
>> ...text here...
>>
>>
>> This renders quite badly, as the "Title" is the same size (<h1>) as the
>> "Section"s.
>>
>> Is there any way to force reST to start headings at <h2>, or (less
>> preferable) to skip automatic title detection?
>>
>> Note: This needs to be rendered by a system I don't control, so I can't
>> just throw CSS at the problem.
>
> Please see the FAQ:
> http://docutils.sourceforge.net/FAQ.html#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why

Sorry, but that is unhelpful. Again, I *don't control* the process used 
to generate HTML. Therefore, unless there is a way to specify 
configuration in the .rst itself (if there is, it's not documented 
obviously enough), I can't use either of the solutions in the FAQ (both 
of which I already knew about).

I need a solution that can be implemented with *only* changes to the 
.rst input file.



So far the best I have come up with is to add:

  .. disable title promotion

...to the very beginning of the document (note the leading indent; the 
text after the comment is of course arbitrary). The rendering is 
tolerable but makes it impossible to have the first heading be a title, 
and adds a useless <blockquote> element to the resulting HTML.

Given that this is apparently a common problem, it seems to me that 
there should be a way to handle this more gracefully in the reST syntax 
itself...

-- 
Matthew