Consider using explicit markup for each section to avoid numbering-related classes

[hubgit]

If the template wraps each section explicitly in a <section> tag, and uses h1, h2, etc + section > section > … to indicate the depth of nesting, then it's possible to avoid all the .counter-skip classes by only applying the numbering to headings inside section elements.

Here's an example: https://github.com/thomaspark/pubcss/compare/master...hubgit:explicit-sections

The article layout basically looks like this:

<article>
  <header>
    <h1>Article Title</h1>
    <div>…</div>
  </header>

  <section>
    <h2>Section heading</h2>
    <p>…</p>
  </section>

  <section>
    <h2>Section heading</h2>
    <p>…</p>

    <section>
      <h3>Subsection heading</h3>
      <p>…</p>
    </section>

    <section>
      <h3>Subsection heading</h3>
      <p>…</p>
    </section>
  </section>

  <footer>
    <div>…</div>
  </footer>
</article>

[hubgit]

Running the HTML5 Outliner bookmarklet on the updated HTML shows that the outline is improved:

compared to the current sample HTML, where most of the sections are nested under the Introduction:

[thomaspark]

Thanks for opening up the issue. I agree that the less special classes we can rely on, the better. The HTML Outliner output for your markup turns out great, so that is definitely a point in your favor.

My approach came from trying to make the markup as simple and intuitive as possible. One of my concerns was that for something like subsubsections, you end up with a pretty complex nesting structure as compared to the more linear structure that coding novices and/or Word users might be comfortable with (a la Markdown). It also increases the chances of unmatched tags, or simply forgetting to wrap section tags.

I'll experiment with making the PubCSS markup compatible with Paper Now, and see if I run into any issues with my themes while doing that.

[hubgit]

It does seems like requiring sections for every level might be too much to ask of articles authored in Markdown (and in fact Paper Now, where I'm hoping to use the PubCSS styles) only adds a single level of explicit sections.

However, the PubCSS template does already use some <section> and <figure> markup, so maybe a good compromise would be to require at least one <section> - and only apply the numbering inside <section> elements - while using the heading elements (h1, h2, h3, etc) for the counter increments and resets.

The main requirement then would be that the heading elements used (h1, h2, h3, etc) accurately reflect the level of nesting, i.e. only a single h1 (the article title), and no jumping from h2 to h4.

[hubgit]

Here's an implementation of that idea: https://github.com/thomaspark/pubcss/compare/master...hubgit:heading-sections

The main changes are

• removing the <section> tags that don't have an associated heading
• wrapping the main article content in a <section>
• moving the article metadata into the <header>

[thomaspark]

I like the changes. Having just one <section> wrap the article makes the markup even more flat and markdowny.

However, I think I prefer how in the current version of PubCSS, the heading number corresponds with the depth of numbering: h1 for 1, h2 for 1.1, h3 for 1.1.1. Starting each new section with h2 could be counterintuitive, although I understand the reasoning behind it.

I also like that all of the metadata is tidily contained in <header>.

There was one problem I ran into with this. A margin-bottom needs to be set on .authors. No problem if there's only one row of .authors. But when a second .authors is added (like here), there needs to be a way to select only the last .authors to apply the margin to.

If <header> only contains author info (which is the case right now), I can use header > :last-child. But that no longer works if additional metadata like keywords and copyright follows it. One idea could be to give .authors a unique tag, and select with :last-of-type. It'd be a mild abuse of tags, but forgivable.