Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(macros/DefaultAPISidebar): add Tutorial section #7646

Merged
merged 5 commits into from
Nov 25, 2022

Conversation

wbamberg
Copy link
Collaborator

@wbamberg wbamberg commented Nov 22, 2022

Summary

This adds support for multi-page tutorials to DefaultAPISidebar, which will enable us to get rid of two custom sidebar macros: CanvasSidebar and WebGLSidebar.

Problem

Almost all pages in Web/API use one of two sidebars: DefaultAPISidebar for API overviews and guides, and APIRef for everything else. However there are four custom sidebars which exist only for a single API each.

Two of the custom sidebars are CanvasSidebar and WebGLSidebar. I would like these custom sidebars to be retired, and for us only to use the normal ones. However, these sidebars have one feature which we can't currently support in DefaultAPISidebar: a multi-page tutorial:

Screen Shot 2022-11-22 at 12 01 42 PM

This is distinct from single-page guides and should not be dumped in there.

Solution

This PR adds a feature to DefaultAPISidebar that looks for a "tutorial" key in GroupData, that is expected to contain a multi-page tutorial given in reading order. If DefaultAPISidebar finds one of these it renders a "Tutorial" section in the sidebar.

This PR doesn't have a hard dependency on mdn/content: it can be merged without any corresponding mdn/content PR and should not break anything.

However, to see the "Tutorial" section it will need an mdn/content update. I've pushed an update to https://github.com/wbamberg/content/tree/use-defaultapisidebar-tutorials so you can see it working. The mdn/content update does three things:

  • add a "Tutorial" entry to L10nCommon.json, so we can label the "Tutorial" section
  • add a "tutorial" component to the GroupData for WebGL
  • update the WebGL overview page to use DefaultAPISidebar instead of the custom sidebar

If this PR is accepted I will update all the WebGL and Canvas docs to use DefaultAPISidebar, then deprecate their custom sidebars.

Screenshots

Before

Screen Shot 2022-11-22 at 12 14 35 PM

After

Screen Shot 2022-11-22 at 12 14 49 PM


How did you test this change?

@github-actions github-actions bot added the macros tracking issues related to kumascript macros label Nov 22, 2022
@caugner caugner self-requested a review November 24, 2022 20:38
@github-actions github-actions bot added the merge conflicts 🚧 Please rebase onto or merge the latest main. label Nov 25, 2022
@github-actions
Copy link
Contributor

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

@github-actions github-actions bot removed the merge conflicts 🚧 Please rebase onto or merge the latest main. label Nov 25, 2022
@caugner caugner changed the title Support tutorials in DefaultAPISidebar feat(macros/DefaultAPISidebar): add Tutorial section Nov 25, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
macros tracking issues related to kumascript macros
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants