getpelican/pelican

Pelican 4.9's `simple` theme uses `<h2>` inconsistently

cpitclaudel opened this issue · 3 comments

cpitclaudel commented

  • I have read the Filing Issues and subsequent “How to Get Help” sections of the documentation.

  • I have searched the issues (including closed ones) and believe that this is not a duplicate.

  • OS version and name: Ubuntu 22.04.4 LTS

  • Python version: Python 3.10.12

  • Pelican version: 4.9.1

  • Link to theme: simple

  • Links to plugins: None

Issue

In #3234 some <h1>s were changed to <h2>s, but the results are not consistent. In fe4f1ec titles were made to be uniformly h1s; then in #3234 part of the change was reverted.

  • On index pages, the title of the index now lives at the same level as individual index entries; for example, All articles changed back from h1 to h2, but individual article titles remained h2s
  • Generally, the use of h2 is inconsistent with other themes, especially notmyidea
  • Page titles and top-level section titles now live at the same level, both h2s. In 4.8 this problem existed with articles but not pages (see repro below), and it was fixed in fe4f1ec and then reverted in #3234 (both happened before 4.9).

Here is a minimal article and how Pelican compiles it:

====
 H1
====

:author: me
:date: 2024-08-01

H2
==

H3
--

Generated HTML:

<article>
  <header>
    <h2>
      <a href="[/h1.html](view-source:file:///h1.html)" rel="bookmark"
         title="Permalink to H1">H1</a></h2>
 
  </header>
  <div class="section" id="h2">
<h2>H2</h2>
<div class="section" id="h3">
<h3>H3</h3>
</div>
</div>

In contrast, here is the HTML produced by the notmyidea, which consistently uses h1, h2, and h3:

  <article>
    <header>
      <h1 class="entry-title">
        <a href="/h1.html" rel="bookmark"
           title="Permalink to H1">H1</a></h1>
    </header>

    <div class="entry-content">
    […]
<div class="section" id="h2">
<h2>H2</h2>
<div class="section" id="h3">
<h3>H3</h3>
</div>
</div>

(Pages have the same issue, whereas before it was only articles.)

CC @pauloxnet

justinmayer commented

@pauloxnet: Any thoughts on this issue related to one of your previous PRs?

pauloxnet commented

@pauloxnet: Any thoughts on this issue related to one of your previous PRs?

Sorry, I've missed that one.

Your examples are missing the full generated html.

This is an example post I put in a Pelican generated project that uses the simple theme.

Title: Hello World!
Date: 2024-09-12 15:00
Category: Article

### Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim aeque doleamus animo, cum corpore dolemus, fieri tamen.

This is the html generated by Pelican (I reformatted it to paste here):

<!DOCTYPE html>
<html lang="en">

<head>
  <title>paulox - Hello World!</title>
  <meta charset="utf-8" />
  <meta name="generator" content="Pelican" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>

<body>
  <header>
    <hgroup>
      <h1><a href="/">paulox</a></h1>
    </hgroup>
    <nav>
      <ul>
        <li><a href="/category/article.html" aria-current="page">Article</a></li>
      </ul>
    </nav>
  </header>
  <main>
    <article>
      <header>
        <h2>
          <a href="/hello-world.html" rel="bookmark" title="Permalink to Hello World!">Hello World!</a>
        </h2>
      </header>
      <h3>Lorem ipsum</h3>
      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore
        magnam aliquam quaerat voluptatem. Ut enim aeque doleamus animo, cum corpore dolemus, fieri tamen.</p>
      <footer>
        <p>Published: <time datetime="2024-09-12T15:00:00+02:00">
            gio 12 settembre 2024
          </time></p>
        <address>
          By <a href="/author/paolo-melchiorre.html">Paolo Melchiorre</a>
        </address>
        <p>
          Category: <a href="/category/article.html">Article</a>
        </p>
      </footer>
    </article>
  </main>
  <footer>
    <address>
      Proudly powered by <a rel="nofollow" href="https://getpelican.com/">Pelican</a>,
      which takes great advantage of <a rel="nofollow" href="https://www.python.org/">Python</a>.
    </address>
  </footer>
</body>

</html>

As you can see there is an H1 which is the blog title and the post title is an H2.

Best practice is to not use H1 more than once in a page (see "Avoid using multiple < h1 > elements on one page")

In the simple theme, the site title is in h1, the post title is consequently in h2 and therefore the paragraph titles you should use in a post should be h3, h4, h5 or h6, if you want to be consistent from an accessibility point of view (see Accessibility).

The headers in the simple theme are consistent and follow the best practices above, but if you want a different result I recommend creating a new theme rather than modifying the simple theme which is intended as a starting point.

P.S. I hope I've made it clear, unfortunately I won't have time to follow up on this issue in the next few days so I might not respond before October.

  • ❤️1
cpitclaudel commented

Thanks for your reply! I this there was a misunderstanding.

You write "In the simple theme, the site title is in h1, the post title is consequently in h2 and therefore the paragraph titles you should use in a post should be h3, h4, h5 or h6, if you want to be consistent from an accessibility point of view.", but unfortunately I don't think this works:

  1. This solution requires manually adjusting title levels. This is quite brittle: it becomes impossible to switch between themes, because the simple theme now assumes that posts are going to be written differently from other themes.

  2. This solution is not applicable to reST, because users don't have control on absolute title depth in reST (only relative).

It seems like the "right" solution would be to remove the h1 from the website title. Alternatively, the solution could be to shift all titles one level down when compiling. What you propose above is to do it by hand (adjust all titles by adding an extra #), but this only works in Markdown, not in reST.

  • 👍1