[Docutils-users] forcing heading levels

[Matthew Woehlke]

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.

[David Goodger]

On 10 January 2014 13:46, Matthew Woehlke

Post by Matthew Woehlke
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

[David Goodger]

Post by David Goodger

Post by Matthew Woehlke
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.

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?

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

Post by David Goodger

Post by David Goodger

Post by Matthew Woehlke
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.

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.

Fair enough. Apologies for the confusion.

Post by David Goodger

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.

I'm not sure. I can place one in the same directory as my .rst, but I have
no idea if it will be used.

Post by David Goodger
What is the environment in which the HTML is being generated?

It's a server that generates dynamic content by fetching an .rst file from a
git repository and producing HTML on demand. (Vaguely similar idea to
github's automatic rendering of .rst, but it's not github.)
I probably *could* go monkey with the server if I really had to (it's an
internal thing developed and run by a coworker), but a general patch risks
breaking things for other people, and a location-specific hack is getting
rather egregious.
Modifying it to try to fetch a configuration file might be okay though.

That sounds like the simplest solution. You'll want a file called
"docutils.conf" in the same directory as your reST file.
For details, see
http://docutils.sourceforge.net/docs/user/config.html#configuration-files

Post by David Goodger

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

Right. Alas, it has no effect (something about how the server generates the
HTML ignores what reST would otherwise specify the title to be; it doesn't
work with "real" titles either). It would be nice (but not critical) to have
an <h1 class="title"> though instead of a plain <h1>.
Thanks for the tip anyway.

Post by David Goodger

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.

Really? There is a FAQ about how it...
I may have a unique wrinkle,

It's the unique wrinkle that I've never seen before.

but it seems to me it would be useful if there
was a syntatic way to solve the FAQ.

Yes, it would, and that has come up before. But there are security
concerns, and ultimately it depends on somebody having enough round
tuits for implementation, which hasn't happened yet. See
http://docutils.sourceforge.net/docs/dev/todo.html#misc-settings

[Matthew Woehlke]

Post by David Goodger

Post by David Goodger

Post by Matthew Woehlke
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.

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.

Fair enough. Apologies for the confusion.

Post by David Goodger

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.

I'm not sure. I can place one in the same directory as my .rst, but I
have no idea if it will be used.

Post by David Goodger
What is the environment in which the HTML is being generated?

It's a server that generates dynamic content by fetching an .rst file
from a git repository and producing HTML on demand. (Vaguely similar
idea to github's automatic rendering of .rst, but it's not github.)

I probably *could* go monkey with the server if I really had to (it's an
internal thing developed and run by a coworker), but a general patch
risks breaking things for other people, and a location-specific hack is
getting rather egregious.

Modifying it to try to fetch a configuration file might be okay though.

Post by David Goodger

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

Right. Alas, it has no effect (something about how the server generates
the HTML ignores what reST would otherwise specify the title to be; it
doesn't work with "real" titles either). It would be nice (but not
critical) to have an <h1 class="title"> though instead of a plain <h1>.

Thanks for the tip anyway.

Post by David Goodger

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.

Really? There is a FAQ about how it...

I may have a unique wrinkle, but it seems to me it would be useful if
there was a syntatic way to solve the FAQ.

[Matthew Woehlke]

Post by David Goodger

Post by Matthew Woehlke
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.

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