Guides get listed twice
DefaultAPISidebar lists guides in the sidebar. It takes guides from subpages of the overview page and from the guides listed in the group. If a single guide appears in both places, it gets listed twice in the sidebar.
See e.g.
- https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API
- https://developer.mozilla.org/en-US/docs/Web/API/Media_Streams_API
- https://developer.mozilla.org/en-US/docs/Web/API/WebVR_API
This seems like an easy fix: have DefaultAPISidebar check the URLs and remove duplicates.
Unfortunately it isn’t, because of page moves and redirects. Suppose a guide page is initially created outside the API overview page, and is listed in GroupData under that URL. Then we move it under the API overview page, it will appear twice and a simple check of the URLs will not show that. Perhaps page JSON can tell us about redirects? - but still this doesn’t look like a good direction.
My first preference here was to fix this by removing the “guides” property of GroupData and only looking for guides as subpages of the API overview page. That seems simpler, and a rule that guides should live under the API overview page seems good generally for documentation coherence.
However there are a couple of problems: the obvious one is that sometimes there might be a good reason for guides to live outside the API subtree. Perhaps we should give writers that freedom. The less obvious one (which is more convincing to me) is that writers probably want to order the guides in the sidebar, like:
- getting started with the foo API
- advanced uses of the foo API
- some really niche stuff about the foo API
The WebVR API sidebar is quite a good example of that. The first half of the sidebar lists guides as they are returned by subpages, and it doesn’t make sense:
- Using VR controllers with WebVR
- Using the WebVR API
- WebVR concepts
The second half has the same guides in the order they come in GroupData, and does make sense:
- Using the WebVR API
- WebVR concepts
- Using VR controllers with WebVR
So I think we should change the macro so it doesn’t look in API overview subpages. Correspondingly, we’ll need to add “implicit” guide pages to GroupData.