Support themes generically

[ykrods]

Describe the feature

Hi ablog developers,

This issue is a bit long, so please feel free to read it when you have time ☕ .

Related: #310, #108

Goal

Discuss a generic approach for supporting Sphinx themes in ablog, instead of adding theme-specific support on a case-by-case basis.

Current situation and key points

• ablog provides its own page.html template, but it does not coexist well with page.html provided by external themes.
• By default, ablog’s page.html takes precedence over the theme’s template.
• When skip_injecting_base_ablog_template is enabled in conf.py, ablog’s page.html is not used.
• When the theme option ablog_inject_templates_after_theme is enabled, the theme’s templates take precedence.
• Using the theme’s templates usually resolves layout issues, but some features provided by ablog are no longer rendered as HTML (this is a trade-off):
  • Links to RSS/Atom feeds
  • Link to Font Awesome CSS
  • Previous/next post navigation
  • Disqus comment section

Possible approach

To avoid this trade-off, one possible approach is to extend the theme’s templates from ablog’s templates, and inject ablog-specific elements there.

This approach is already used in the Pull Request #310:

https://github.com/SilverRainZ/ablog-with-shibuya/blob/6f6adbc896faca10365a947348de681b523a49e6/src/ablog/templates/page.html#L1

Regarding the use of a theme name as a prefix:

Sphinx adds both the theme directory and its parent directory to the template search paths, which allows templates to be referenced with a theme-name prefix.

Although I have not fully traced the original motivation, this mechanism likely exists to avoid infinite loops when using extends "page.html" inside page.html itself.

Relevant code in Sphinx:

https://github.com/sphinx-doc/sphinx/blob/cc7c6f435ad37bb12264f8118c8461b230e6830c/sphinx/jinja2glue.py#L172-L198

One important caveat is that themes can have inheritance relationships.
Even if a_theme/page.html does not exist, parent_theme/page.html may exist and be used for rendering.

Therefore, when deciding which template ablog’s page.html should extend, it may be necessary to traverse the theme inheritance chain.

Another challenge: content blocks

Another challenge for generalization is that the Jinja2 block that contains the main content (the HTML converted from reST or Markdown, stored in the body variable) differs between themes.

For ablog’s previous/next post navigation and the Disqus comment section, these elements need to be placed after the article content. However, the appropriate block differs depending on the theme.

alabaster (basic)

https://github.com/sphinx-doc/sphinx/blob/cc7c6f435ad37bb12264f8118c8461b230e6830c/sphinx/themes/basic/page.html#L2-L5

• {{ body }} is placed inside the {% block body %}
• The {% block content %} wraps the {% block body %}

furo

https://github.com/pradyunsg/furo/blob/4e7a7e0308bfdfef84db3bb3759278c431ebd97f/src/furo/theme/furo/page.html#L111

• {{ body }} is placed inside the {% block content %}
• The {% block body %} wraps the {% block content %}

shibuya

https://github.com/lepture/shibuya/blob/a98526255a61675bbb97e85d7a5087ee4b878359/src/shibuya/theme/shibuya/layout/default.html#L49

• {{ body }} is placed inside the {% block content %}
• The {% block body %} wraps the {% block content %}

pydata-sphinx-theme

https://github.com/pydata/pydata-sphinx-theme/tree/main/src/pydata_sphinx_theme/theme/pydata_sphinx_theme

• {{ body }} is placed inside the {% block body %}
  • This theme does not provide page.html, so basic/page.html is used via inheritance
• As with basic, the {% block content %} wraps the {% block body %}

Proposed solution

Prototype implementation

At least for the themes listed above, it seems sufficient to control whether the comment section is inserted into the content block or the body block.

As a prototype, I implemented an approach that adds a theme-specific setting theme_content_block in conf.py to select one of the two.

The code diff is available here:

PR: #324

And the ablog documentation built with different themes can be found below:

• furo: https://ykrods.github.io/ablog/furo/
• shibuya: https://ykrods.github.io/ablog/shibuya/
• pydata-sphinx-theme: https://ykrods.github.io/ablog/pydata-sphinx-theme/

[ykrods]

Ultimately, since some theme-specific handling is unavoidable, another possible approach is to switch behavior internally in ablog based on the active theme (without exposing theme_content_block as a public setting). I would appreciate any thoughts or suggestions on how this should be designed.

[nateskulic]

I think page.html is overextended causing conflicts. Ablog's page.html should be named post.html (or something). Ablog may extend the base page.html (in post.html), but the post's content should be rendered in a separate template. Themes supporting Ablog would then implement post.html. Just an idea.

[ykrods]

@nateskulic

I think the idea of creating an Ablog-specific template is good 👍

According to the official documentation, it seems possible to switch the template from page.html via the html-page-context event handler.

reference: https://www.sphinx-doc.org/en/master/extdev/event_callbacks.html#event-html-page-context

On the other hand, as you commented, if we add post.html, its contents would probably be {% extends "page.html" %}. However, it remains a problem that some themes render {{ body }} in the content block while others render it in the body block, because we need to choose the block used to render the content in ablog/catalog.html and ablog/collection.html, which are used for like tag or archive pages.

ablog/src/ablog/templates/ablog/catalog.html

Lines 1 to 3 in 45d9f3d

	{%- extends "page.html" %} {% macro postlink(post) -%} {% if post.external_link
	-%} {{- post.external_link -}} {% else %} {{- pathto(post.docname) }}{{
	anchor(post) -}} {%- endif %} {%- endmacro %} {% block body %} {% for collection

ablog/src/ablog/templates/ablog/collection.html

Line 1 in 45d9f3d

{%- extends "page.html" %} {% block body %} {% macro postlink(post) -%} {% if

It might be possible to solve this by avoiding extends in those pages and instead implementing them so that the HTML is injected into {{ body }} in post.html ( or blog.html), but I’m not sure whether this is actually feasible.

[ykrods]

Now that I have confirmed we can render body in the html-page-context event handler, I put a improved implementation:

#325

• On catalog, collection and redirect pages, inserting the content via the {{ body }} variable avoids depending on a theme’s internal structure.

• postnavy.html and disqus.html (comment section) are intended to be added by users via configuration, similar to a sidebar. Whether that’s possible depends on the theme templates.

  • pydata-sphinx-theme: users can specify templates via article_footer_items theme option
    • https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html
  • shibuya: although it seems to be designed for advertisements, users can place partials/page-bottom.html and include postnavy.html
    • https://shibuya.lepture.com/customisation/advertisement/#templates
  • Others: if there is no hook point, we’ll need to guide users to provide a custom ablog/blog.html template