Custom footers lose the { Light | Dark | Auto } appearance selector

[krilnon]

Description

If you use DocC's --experimental-enable-custom-templates flag and provide a custom footer.html, users lose the ability to override their system's light/dark appearance preference. This happens because DocC-Render puts its color scheme selector in the footer, which is removed if a project provides a custom footer.

I worked around this for the Swift book in: swiftlang/swift-book#110, but this bug tracks a more general solution.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

Custom footers do not need to implement their own appearance toggle.

Actual behavior

Custom footers need to implement their own appearance toggle.

Steps To Reproduce

No response

Swift-DocC-Render Version Information

No response

[natikgadzhi]

The actual toggle is in src/components/ColorSchemeToggle.vue.

I wonder what the right approach here looks like:

1. We could conditionally (or always?) render the color scheme selector in the bottom of the left sidebar, stuck to the bottom of the viewport, instead of the footer. That way, custom footer won't remove it.
2. Or we could document that by using a custom footer, the user will give away the color scheme selector.

@mportiz08, what would be a better approach here?

[j-f1]

It might be possible to define a <color-scheme-toggle> custom element that could be placed in footer.html to render the color scheme picker. I’m not sure how easy that would be to integrate into the existing Vue app/state management system, though.

[mportiz08]

The actual toggle is in src/components/ColorSchemeToggle.vue.

I wonder what the right approach here looks like:

1. We could conditionally (or always?) render the color scheme selector in the bottom of the left sidebar, stuck to the bottom of the viewport, instead of the footer. That way, custom footer won't remove it.

Although it would be nice to have quicker access to the toggle, I personally worry about the alternative of having it always present at a fixed location on the viewport. The left sidebar isn't present for tutorial pages at the moment either, so it doesn't necessarily fit in naturally within that component.

I do tend to feel like this would most likely be resolved with a better design for this setting that impacts global settings for the website where it fits on every page without the need to be attached to the footer.

2. Or we could document that by using a custom footer, the user will give away the color scheme selector.

@mportiz08, what would be a better approach here?

It would be good to document this somewhere, although this limitation is one of the reasons that the custom header/footer are experimental/undocumented features at the moment.

It might be possible to define a <color-scheme-toggle> custom element that could be placed in footer.html to render the color scheme picker. I’m not sure how easy that would be to integrate into the existing Vue app/state management system, though.

Something like that could be an interesting solution, essentially letting custom header/footers include this component if they want, although I agree that it is likely something that might be complex to make work.