feat(macros): rewrite SVG sidebar

[wbamberg]

Summary

This PR rewrites the current SVG sidebar, SVGRef.ejs.

Problem

The immediate reason for this is that the current sidebar uses tags, and we want to stop using tags.

But the current sidebar is also not very useful: it only lists elements, not attributes or any guide/tutorial content.

Solution

This sidebar is more or less modelled on the partly-new HTML sidebar, since the domain has a similar structure:

• Tutorials
• Reference
  • Elements
  • Attributes
• Guides

Some notes and things.

• although there's only one tutorial, I opted for "Tutorials" plural, because otherwise it would be hard I think to put the tutorial steps under a disclosure arrow, and there are enough steps that this seems warranted. Also the docs kind of imply that there was intended to be > 1 tutorial at some point in the future. It's unfortunate though that there isn't a separate page for the Introducing SVG from Scratch tutorial, because it means we need a localized string for the label. Maybe there's a better solution here?
• under "Guides" I stuck some but not all of the top-level pages from https://github.com/mdn/content/tree/main/files/en-us/web/svg. Some of them I left out because they seemed really really out of date. But maybe I should have made different choices?

Screenshots

Before

collapsed:

expanded:

After

collapsed:

expanded:

Testing

Testing: fire up yarn dev and visit:

• http://localhost:3000/en-US/docs/Web/SVG
• http://localhost:3000/fr/docs/Web/SVG

Fixes #7171.

@teoli2003 , @hamishwillee

[teoli2003]

From a content perspective

[caugner]

@wbamberg Let's use the PR template whenever possible, and add before/after screenshots whenever the UI changes. 😉

[wbamberg]

@wbamberg Let's use the PR template whenever possible, and add before/after screenshots whenever the UI changes. 😉

Sorry. Updated.

[hamishwillee]

Yes, this is much better than what we have.

FWIW IMO it would be better if the structure were defined in mdn/content data - e.g. tutorial etc. rather than headings and content being in yari. Generally it would be nice to never have to go near yari.

[wbamberg]

Yes, this is much better than what we have.

FWIW IMO it would be better if the structure were defined in mdn/content data - e.g. tutorial etc. rather than headings and content being in yari. Generally it would be nice to never have to go near yari.

Thanks Hamish! We just talked about this but ftr: @caugner and I talked about exploring a future for sidebars where they are specified by writers in JSON and built by Yari. I'm going to use this PR #8132 to explore that idea. If you look at the sidebar there, it's basically in three pieces:

• a string map for l10n - as far as possible I'd like to use page titles for sidebar labels instead but it may not always be possible. But we could imagine these strings living in L10n-Common.json in mdn/content. That way, localizers don't have to edit KS any more.
• a JSON structure that specifies the sidebar. We could also imagine these living under https://github.com/mdn/content/tree/main/files/jsondata, and being maintained by writers. That way writers don't have to edit KS to specify sidebars any more.
• some JS that builds HTML, given the other things. We could imagine this living in Yari.

We could also imagine a JSON file in https://github.com/mdn/content/tree/main/files/jsondata that maps directories (and maybe page types) to sidebars. Then Yari could auto-add the correct sidebar to each page, and we wouldn't need the KS calls in content at all any more.

There are a lot of details to work out and some sidebars that would be hard to accommodate (like DefaultAPISidebar). But this is the general idea.

[hamishwillee]

@wbamberg ^^^ That is a promising thing to hear. I sounds like we are very aligned.
In particular, if information can be fetched from a page, we should do so. So the only l10n would be for text that isn't in a page - such as a "grouping".

My thinking is that in the ideal world you could specify a sidebar like {{Sidebar("link to json file name "or some alias for it that is defined somewhere")}}. The sidebar would then be built on that definition. So just one macro "under the hood" for any sidebar.
Perhaps some additional magic to allow sidebars to be automatically added based on page-type metadata for some types.

[caugner]

My thinking is that in the ideal world you could specify a sidebar like {{Sidebar("link to json file name "or some alias for it that is defined somewhere")}}. The sidebar would then be built on that definition. So just one macro "under the hood" for any sidebar.
Perhaps some additional magic to allow sidebars to be automatically added based on page-type metadata for some types.

Ideally we would simply show the sidebar that references the page, and avoid that a page is referenced in multiple sidebars (so that, if a user clicks on a link in a sidebar, the resulting page will have the same sidebar).

[github-actions]

This pull request has merge conflicts that must be resolved before it can be merged.

[hamishwillee]

Ideally we would simply show the sidebar that references the page, and avoid that a page is referenced in multiple sidebars (so that, if a user clicks on a link in a sidebar, the resulting page will have the same sidebar).

@caugner In most sites that would be true, but in MDN the ability for pages to appear in different sidebars is a "feature". For example, consider navigator.connection. It is "part of" the Navigator interface but it is also part of the NetworkInformation API. In other words it is genuinely "right" to have it in both sidebars.

[hamishwillee]

BTW, what has to happen to get this PR in?

[wbamberg]

Ideally we would simply show the sidebar that references the page, and avoid that a page is referenced in multiple sidebars (so that, if a user clicks on a link in a sidebar, the resulting page will have the same sidebar).

@caugner In most sites that would be true, but in MDN the ability for pages to appear in different sidebars is a "feature". For example, consider navigator.connection. It is "part of" the Navigator interface but it is also part of the NetworkInformation API. In other words it is genuinely "right" to have it in both sidebars.

Yeah, this would be hard in our current IA. See also, Learn content, which is duplicated in domain-specific areas.

For the medium term (say the next three years) I would be totally happy with a map in /jsondata that says things like:

• if a page is under (say) Web/CSS, then it gets the CSS sidebar
• if a page is under (say) Web/JavaScript and it has page-type javascript-class, etc, then it gets the JSRef sidebar

I think that would work fine, and would avoid the worst problem, which is that authors have to add {{CSSRef}} a thousand times, and if they forget, no sidebar.

[hamishwillee]

Agree ^^^. What needs to happen to get this PR in?