How to modify pages titles?

[cglacet]

I'm trying to modify a page title without having an <h1> tag in my page. Is it possible?

The current behaviour when setting html_title = 'test' is to output <no title> test. I would for example like to remove the <no title> part so my page title is equal to html_title. Do I need to create a template for that?

[bashtage]

Can you be a bit more specific? In particular, can you posted the relevant parts of your conf and the rst page?

[cglacet]

Hmm, I'm not sure I get what you mean, but here is my a test.rst file:

file without header/title.

And here are the relevant parts of the config.py:

import sphinx_material

project = 'Kune'
release = '0.1'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx_copybutton',
]

html_sidebars = {
    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
}

extensions.append("sphinx_material")
html_theme_path = sphinx_material.html_theme_path()
html_context = sphinx_material.get_html_context()
html_theme = "sphinx_material"

html_theme_options = {
    'nav_title': 'Kune servers documentation',
    'globaltoc_depth': 3,
    'globaltoc_collapse': True,
    'globaltoc_includehidden': True,
}

Using this configuration, the resulting HTML tag is <title>&lt;no title&gt; — Kune 0.1 documentation</title>.

I would like to know how to make the resulting tag <title>Kune 0.1 documentation</title> or any other title I could decide to be the default title for no-headings-pages.

EDIT, also, I guess you already know that, if I set html_title = "Another title" I'll get <title>&lt;no title&gt; — Another title</title> which doesn't solve the "<no title>" problem.

[bashtage]

This seems to be Sphinx's default for a page with no title. This "title" (<no title>) is then passed to the template engine which is then rendered in place fo the title.

This could be addressed here, but it may not be the right place for a fix. Sphinx might be the right place to have an option to override the default value of <no title> to be an empty string.

Normally the title is read from the pages top heading.

[bashtage]

https://github.com/sphinx-doc/sphinx/blob/af62fa61e6cbd88d0798963211e73e5ba0d55e6d/sphinx/environment/collectors/title.py#L53

Does not seem to provide a method to override.

[cglacet]

Thanks, I'll move this to sphinx then and patch it on my side in the mean time.

[bashtage]

Great. I'd rather not try and fitis here since it would be pretty hacky, something along the lines of

if title =! "<no title>":
    full_title = title + " - ' + html_title

which is very dependent on how sphinx renders "no title". I would suggest that Sphinx could add an enhancement for conf.py that would be something like include_empty_page_title which would be True or False. Alternatively, it could just have a default page title, e.g., default_page_title = "" which would then be reasonable to filter for so that title would only be added when not-empty.

[cglacet]

That patch is not enough sadly, there is another place that treats title apparently.

Here is how I patched it (at least to remove the <no title> part), in my conf.py:

from docutils import nodes
from sphinx.application import Sphinx
from sphinx.environment.collectors.title import TitleCollector

_process_doc = TitleCollector.process_doc

def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
    if doctree.traverse(nodes.section):
        _process_doc(self, app, doctree)
    else:
        titlenode = nodes.title()
        app.env.titles[app.env.docname] = titlenode
        app.env.longtitles[app.env.docname] = titlenode

TitleCollectorprocess_doc = process_doc

This renders — test, for now I can't get rid of the —.

Another problem is that, even with setting a title manually in the toctree: A test .rst without any section <test>, the entry doesn't show.

[bashtage]

The - removal would need to come from sphinx-material. If title is empty, then the page title should be html_title if present, and it not, nothing (which might not be 100% compliant in HTML).

[cglacet]

The title wouldn't be empty, it would be equal to html_title. Here the problem is that it's equal to f"— {html_title}".

[bashtage]

That is what I mean. One challenge is that html_title has been escaped before it get to templating and the - has been manually inserted, and so some string parsing is needed. Not the end of the world, but starting to feel fragile. This hardcoded behaviour is a misfeature of Sphinx IMO.

[bashtage]

There is a start in#81. It will need to become opt-in before it can be merged.