Custom API sidebars
Apart from DefaultAPISidebar, there are four APIs which have their own custom sidebars, implemented using their own custom macros.
They are:
As we’ve seen, DefaultAPISidebar is a pretty powerful beast. So we could look at what these four sidebars are doing that isn’t accommodated by DefaultAPISidebar. Perhaps we could add these things into DefaultAPISidebar, then we could remove these custom macros. This would help reduce our maintenance burden and provide a more consistent experience for MDN users.
It turns out that all of these sidebars are “static sidebars”: that is, they’re not driven by data sources like GroupData or wiki APIs like subpagesExpand()
. Instead, they’re basically big lists of links organised in a tree.
CanvasSidebar
The Canvas sidebar looks like this:
-
API Overview page
-
Canvas tutorial
-
Examples
-
Interfaces
-
Documentation
- Useful lists
- Contribute
- doc status
- MDN project page
The “Documentation” submenu appears in all four custom sidebars. It seems entirely generic: there’s nothing particular about these four APIs that makes such a submenu useful here but not for other APIs. So we could just build it into DefaultAPISidebar. But I would vote for removing it: apart from the fact that it’s just silly calling a submenu “Documentation”, I don’t think any of these links are useful for 99.9% of our users.
The “Interfaces” submenu is already included in DefaultAPISidebar.
The “Examples” submenu contains three links, one of which goes to an archived doc. The other two could fit happily within the definition of “Guides” in DefaultAPISidebar.
The “API Overview page” is already included in DefaultAPISidebar.
The interesting one here is “Canvas tutorial”, because it’s not just a list of pages which might have an order: it’s a single multi-page tutorial taking you through the whole API. So I think we might want to enable this in GroupData/DefaultAPISidebar.
ServiceWorkerSidebar
The Service Worker sidebar looks like this:
-
API Overview page
-
Service Worker guides
-
Interfaces
-
Related APIs
- list of links to other API overview pages
-
Documentation
- Useful lists
- Contribute
- doc status
- MDN project page
Apart from “Documentation” which we covered above, the only thing not already supported in DefaultAPISidebar is “Related APIs”. We could add support for this, but I’d be inclined to not support it for this tiny use case (2 pages).
WebGLSidebar
The WebGL sidebar looks like this:
-
API Overview page
-
WebGL tutorial
-
Examples and articles
-
Interfaces
-
Documentation
- Useful lists
- Contribute
- doc status
- MDN project page
This looks a lot like the CanvasSidebar. We also have a multipage tutorial, and interfaces, and “Documentation”. I think the links under “Examples and articles” could easily live under “Guides”. So there’s nothing extra here.
WebRTCSidebar
The WebRTC sidebar looks like this:
-
API Overview page
-
WebRTC guides
-
WebRTC tutorials
-
Interfaces
-
Documentation
- Useful lists
- Contribute
- doc status
- MDN project page
This has “Documentation”, like the others, and “Guides”, and “Interfaces”, that are already supported by DefaultAPISidebar. It also distinguishes between “guides” and “tutorials” (note the plural “tutorials”, this is not a single multipage tutorial). I don’t think we should maintain this distinction: I don’t think readers or writers understand it consistently enough. So I think we should include the “tutorials” in “guides”, and then we could implement sidebars for WebRTC using the existing DefaultAPISidebar.
Conclusions
Based on this I think we should:
-
possibly (probably?) add a “tutorial” property in GroupData to enable us to include a single multipage tutorial in the sidebar, and update DefaultAPISidebar to display the tutorial for groups that contain it.
-
make any other updates to GroupData to include guides for these APIs
-
update these pages to use DefaultAPISidebar instead of the custom macro
-
delete these four custom macros