Re: forcing heading levels

On 10 January 2014 14:19, Matthew Woehlke <[email protected]> wrote:
> 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.

Re that "again": In your original email, I understood "render" in its
usual sense, i.e. "render HTML in the browser", and that's a common
enough issue to have a section in the FAQ. I was trying to be helpful.
Specificity earlier would have avoided the misunderstanding.

> 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.

That's not possible, sorry.

Do you have control over the .docutils configuration file? If so, you
can specify the setting there.

What is the environment in which the HTML is being generated?

> 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.

You can use the "title" directive to specify a document title.

> 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...

Your specific problem is not common at all. This is the first I've heard of it.

-- 
David Goodger <http://python.net/~goodger>

------------------------------------------------------------------------------
CenturyLink Cloud: The Leader in Enterprise Cloud Services.
Learn Why More Businesses Are Choosing CenturyLink Cloud For
Critical Workloads, Development Environments & Everything In Between.
Get a Quote or Start a Free Trial Today. 
http://pubads.g.doubleclick.net/gampad/clk?id=119420431&iu=/4140/ostg.clktrk