Html document structure

[xvw]

Hi, first, thanks a lot for your work.
I am creating my own style sheet (for documentation of my possible packages) And I find it quite complicated to make a CSS easy to edit. Yet I think that a simple way to make documents more easily customizable would be to structure the document more "strongly".

For example :

<header>
  <nav>
     <!-- here, the little caml emoji and the Up button --> 
  </nav>
</header>
<div id="...">
  <h1>OCaml package documentation</h1>
  <p>...</p>
</div>
...

The main goal of a more "strongly" structure is to avoid, in the CSS, an abuse of things like that : nav::nth-child(1) { ... }.

[dbuenzli]

My own experience in writing stylesheets is that having too much structure (divitis) precisely leads to have more complex stylesheets.

[lpw25]

I suspect that trying to discuss this at a broad level just leads to a religious dispute. I would rather we considered individual changes to the HTML structure on their own merit. So if possible could you describe a particular set of changes that would make your specific stylesheet easier to implement. That should make it easier to discuss the pros and cons of those specific changes.

[xvw]

My own experience in writing stylesheets is that having too much structure (divitis) precisely leads > to have more complex stylesheets.

You are totally right, do not overdo compartmentalisation.

IMHO, The only really important point (and useful) would be:

the first <nav> should be in a <header> or have a specific class / id:
In this way, it is easy to distinguish it from other

(and whose treatment could be more generic).

[dbuenzli]

the first

should be in a or have a specific class / id:
In this way, it is easy to distinguish it from other

There's no other nav on the page.

[xvw]

Hum... the letters, the tags ?

[trefis]

Oh, I think you're talking about the package index page generated by odig, not the pages generated by odoc!

[dbuenzli]

Indeed, these are easy to address with e.g. .by-{name,tag} nav selectors.

The toplevel nav could be distinguished via an id (e.g. top, hierarchy, tree) wrapping in a header should not be done since those are being used for module names on module pages.

@trefis you'll have to do this on module pages (around here) and I'll have to do it in odig for the main index page.

[xvw]

Oh, I think you're talking about the package index page generated by odig, not the pages
generated by odoc!

My bad... sorry ._.

The toplevel nav could be distinguished via an id (e.g. top, hierarchy, tree) wrapping in a header
should not be done since those are being used for module names on module pages.

You're right. (It was my second proposition)

Thanks a lot.

[trefis]

So, id="top" on nav?

[dbuenzli]

Yes.