Supplementing DocC's output with minimal content in the per-page HTML files

[ronnqvist (David Rönnqvist)]

@benrimmington

@ronnqvist

The information that DocC considers as "the page's content" for this purpose is:

• the "breadcrumbs" that link to the hierarchy of container pages for the current page

Should the semantic element of the "breadcrumbs" list be a nav element?

That's another example of how concise the HTML content should be that I don't know the best answer to. Just like the <section id="Parameters"> and <pre id="Declaration"> examples from the "Open Questions" section, the current implementation has a tested code path that wraps the breadcrumbs list of links (<ul> element) in a <nav> element with an "id" attribute like below, but there's nothing in a docc convert flow that calls that specific code right now.

+ <nav id="Breadcrumbs">
    <ul>
      <li>
        <a href="../../index.html">ModuleName</a>
      </li>
      <li>
        <a href="../index.html">SomeClass</a>
      </li>
      <li>someMethod()</li>
    </ul>
+ </nav>

It's very possible that the current implementation takes conciseness one or two steps too far and that it would be better to walk back the decision to omit "unnecessary" wrapping semantic elements like <section> and <nav> and the decision to omit "unnecessary" "id" attributes that identifies conceptual "sections" (not always a <section> element) like "Breadcrumbs", "Declaration", "Parameters", "Discussion", "Topics", "Relationships", etc.

@benrimmington

@ronnqvist

However, because this isn't the primary focus

There's an unfinished sentence in "Alternatives considered".

Thanks for catching that. I updated the post to finish that sentence like this:

However, because this (people reading the HTML output described in this pitch) isn't the primary focus, I propose that DocC puts the minimal HTML content inside the <noscript> element to avoid the risk of the minimal static content appearing for a flash before Swift-DocC Render replaces it with the full fidelity page.