Tactics for how to present a "disclosure" tag within DocC content

Development Swift-DocC
,
1

This is sort of a "pre-pitch". I ran across and wanted to leverage the equivalent of the HTML tag <details>:

  <details>
    <summary>Click to expand</summary>
    <p>This content is hidden by default and revealed when you click the summary.</p>
    <ul>
      <li>More content here</li>
      <li>Can be any HTML elements</li>
    </ul>
  </details>

Within the guts of DocC, I think <details> would map to its own "kind" of RenderNode. I've not spotted a consistent pattern of how (or if) this can be represented in Markdown. Most examples I've found rely on inlining the HTML.
Since HTML isn't supported as inline content with DocC, is a path to extend DocC to enable this adding a directive?

I'm guessing this isn't the first time this topic's been discussed for DocC, but I didn't spot anything in the history here to know for sure, so figured it was worth asking.

1 Like
2

In my personal opinion I would find it valuable to explore supporting HTML as inline content in the RenderJSON. That would solve not only this, but also similar enhancements like including mathematical expressions or including custom diagrams in the documentation.

DocC already supports inline HTML content in its experimental static-HTML-with-content output. If that's not feasible to support in the RenderJSON then I would consider that as even more reason to prioritize phasing out the RenderJSON in favor of the smaller and faster HTML output.

1 Like
3

I’d much rather expand on RenderJSON’s capabilities rather than give in to HTML, if only because these docs are meant to be used in contexts other than HTML and I hate having to bring a browser all the time in everything.

4

While inline HTML is certainly appealing - and I can think of a couple other use cases where that would be super useful, we've got this intentionally abstracted layer between what DocC generates and what gets rendered. Assuming "inline html" starts to break down that abstraction - kind of punches a hole or escape hatch into it. I wonder if we should keep it abstracted and provide create a RenderJSON representation of the equivalent concept for this. I think there's a pretty straightforward RenderJSON representation possible. I haven't tried it yet, but I think it'll be straightforward.

That original abstraction was set up quite a few years ago now, I suspect with hopes that alternate displays could and would be built on it, but aside from an experimental DocC viewer app on macOS/iOS a few years ago, I've not seen anything presenting a view that wasn't leverging HTML for the display/layout.

@Lancelotbronner I'm curious if you're using the RenderJSON format today for display (beyond or other than a stock HTML in a web page somewhere). Totally my personal curiosity here - I haven't found too many folks consuming that JSON data or its schema.

5

It’s not working yet, but that is the plan! I keep getting interrupted by Uni and new research like the new overload resolution paper that I started implementing in Swift!

1 Like