feat(macros): create a PWA sidebar #8238

wbamberg · 2023-02-17T04:09:26Z

Summary

Adds a new sidebar for the PWA docs: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps

Note: this PR needs to be merged alongside mdn/content#25888.

Problem

PWA docs don't have a usable sidebar.

Solution

This PR adds a new KS macro, PWASidebar, which implements a sidebar for the PWA docs, to support the PWA docs refresh project: mdn/mdn#280.

The sidebar implements the information architecture discussed in the PWA planning doc: https://docs.google.com/document/d/1-skaKXoJ0rKhgBHchTWSTAW5dxrlmVYkPeKUWpet9nE/edit?usp=sharing.

The sidebar is implemented as a model of how we could have JSON-driven sidebars, with a JSON structure defining the sidebar in mdn/content and a little code in Yari that builds a sidebar from that JSON. This would allow us to retire most of the KS sidebar macros (a few complex sidebars like DefaultAPISidebar would need to stay in KS for the time being).

Screenshots

Before

After

How did you test this change?

check out this branch
check out feat(macros): create a PWA sidebar #8238
point that yari branch at this content one, using CONTENT_ROOT: https://github.com/mdn/yari/blob/main/docs/REVIEWING.md
run yarn dev
visit http://localhost:3000/en-US/docs/Web/Progressive_web_apps, and the pages linked in the sidebar.
visit http://localhost:3000/fr/docs/Web/Progressive_web_apps (after editing that page to add the {{PWASidebar}} call)

captainbrosset · 2023-02-20T08:26:23Z

Thanks a lot @wbamberg. Sadly I have no had the time to go through this.
By any chance, could you attach a screenshot of the sidebar here? I know that would help me a lot!

wbamberg · 2023-02-20T19:34:12Z

Sorry Patrick, I forget some people don't live inside this world :).

Not expanded:

Expanded:

The names for tutorials and tutorial steps are placeholders.

One thing worth mentioning is that when an item in the sidebar has a disclosure arrow, like "Your first PWA", (meaning it contains a group of connected subpages, like steps in a tutorial) it can't also be a link to a page (because clicking the label opens the subpages), so if we want an overview page for this we usually end up having that be the first child, like:

* Your first PWA
    * Your first PWA
    * Step 1
    * Step 2
    ...

...this is ugly and I wish we had a better answer here, but it's what we do everywhere.

captainbrosset · 2023-02-21T09:17:02Z

This looks great.

A couple of thoughts:

Do we need to be concerned about the length of the sidebar? The How-to section is likely to contain 15 to 20 topics which, for now, would just be presented in one flat list.
What do you think should go under Reference? We discussed about creating a global PWA reference page which would contain links to all manifest, https, service worker, etc. things. Do you think we should also add a link to manifest, and service worker reference docs in the sidebar directly?
I'm not too worried about the fact that TOC nodes can't also be links. We have the same issue on learn.microsoft.com and I don't find this to be a big issue myself. At least, as a user, I'm not confused about whether I should read some intro content on the TOC node first, or expand it to find the first page inside of it. I see what you mean about having to repeat the title. But I'm sure we can find creative ways to avoid this:
- Tutorials
  - Build a simple PWA
    - Get started
    - Add a manifest
    - Install the PWA
  - Build a more complex PWA
The 2 tutorial names would have to be better than this, but the idea is to find a title for them.

estelle · 2023-02-21T17:56:51Z

this LGTM. I like the idea of nesting subcontent.

I assume, like on https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps/Getting_started, the current section would be open and hilited, and everything else will be closed, which I think will make this nav great UX as long as we don't have every other subject listed in the nav, like the learn section does :|

wbamberg · 2023-02-21T17:58:35Z

I assume, like on https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps/Getting_started, the current section would be open and hilited, and everything else will be closed, which I think will make this nav great UX as long as we don't have every other subject listed in the nav, like the learn section does :|

Yes - and if you try this sidebar out your should see that behavior.

wbamberg · 2023-02-21T18:04:58Z

This looks great.

A couple of thoughts:

Do we need to be concerned about the length of the sidebar? The How-to section is likely to contain 15 to 20 topics which, for now, would just be presented in one flat list.

I think 15-20 is fine in a flat list, but if it looks too big we could create additional categories.

What do you think should go under Reference? We discussed about creating a global PWA reference page which would contain links to all manifest, https, service worker, etc. things. Do you think we should also add a link to manifest, and service worker reference docs in the sidebar directly?

I'd envisaged this is just one page with nothing under it, linking to the reference docs that live elsewhere. We could have links to say https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API direct from the sidebar, and maybe that would be good. We get a bit into sidebar philosophy though :) of whether sidebars should contain links to pages that themselves have a different sidebar. We do this sometimes on MDN, and it works fine now but rules out certain possible futures for sidebars (see https://github.com/orgs/mdn/discussions/124#discussioncomment-4578532 for example: it makes it much harder to use lists of links in sidebars as reusable bits of IA). But like I say, we do this already sometimes, so it is certainly possible.

kumascript/macros/PWASidebar.ejs

caugner · 2023-02-24T10:01:50Z

kumascript/macros/PWASidebar.ejs

+    output += `<li><a href="${baseURL}${item}">${await getTitle(
+      item
+    )}</a></li>`;


Probably makes sense to extract renderLink(), which determines both the href and the text.

If the page does not exist in the current locale, I think we'll want to add (en-US) behind, like web.smartlink() already does (I don't mind not using web.smartlink() for now, but we should extract all these helper methods somewhere before replicating them to another sidebar anyways).

kumascript/macros/PWASidebar.ejs

Co-authored-by: Claas Augner <495429+caugner@users.noreply.github.com>

* upstream/main: (251 commits) chore(deps-dev): bump typescript from 4.9.5 to 5.0.3 in /client/pwa (mdn#8547) chore(deps-dev): bump typescript from 4.9.5 to 5.0.3 (mdn#8543) chore(deps-dev): bump postcss-preset-env from 8.2.0 to 8.3.0 (mdn#8561) chore(deps-dev): bump @types/react from 18.0.31 to 18.0.32 (mdn#8560) chore(advertising): update copies (mdn#8562) fix(client): place hash before headings (mdn#8532) chore(deps-dev): bump ts-jest from 29.0.5 to 29.1.0 (mdn#8559) chore(deps-dev): bump black from 23.1.0 to 23.3.0 in /deployer (mdn#8555) chore(deps-dev): bump webpack-dev-server from 4.13.1 to 4.13.2 (mdn#8558) chore(deps-dev): bump swr from 2.1.1 to 2.1.2 (mdn#8556) chore(deps): bump boto3 from 1.26.99 to 1.26.104 in /deployer (mdn#8557) chore(deps-dev): bump black in /testing/integration (mdn#8554) ci(stage-build): rsync with -j html,json,txt (mdn#8549) ci(stage-build): rsync with -c (mdn#8548) chore(deps-dev): bump react-router and react-router-dom from 6.9.0 to 6.10.0 (mdn#8534) chore(deps-dev): bump @babel/preset-env from 7.20.2 to 7.21.4 (mdn#8544) chore(deps-dev): bump tailwindcss from 3.3.0 to 3.3.1 (mdn#8546) chore(deps): bump @mdn/browser-compat-data from 5.2.46 to 5.2.47 (mdn#8545) chore(deps-dev): bump @babel/core from 7.21.3 to 7.21.4 (mdn#8542) fix(docs): make icons in good/bad examples float (mdn#8531) ...

wbamberg · 2023-04-04T04:12:16Z

I've updated this sidebar with the new pages we've written, and to include the existing pages until we are ready to replace them all. I've also addressed review comments.

Overall structure here is pretty much the same as what we had before.

Details of the content changes are in mdn/content#25888. This PR needs to land with that one.

caugner

LGTM, just two refactoring opportunities (+ one older comment regarding the (en-US) postfix).

caugner · 2023-04-04T09:09:25Z

kumascript/macros/PWASidebar.ejs

+  output += `<li><a href="${baseURL}"><strong>${await getTitle(
+    ""
+  )}</strong></a></li>`;


Let's extract this as renderRootItem() to describe what this does?

caugner · 2023-04-04T09:11:09Z

kumascript/macros/PWASidebar.ejs

+  for (const section of sections) {
+    output += await renderSection(section);
+  }


Let's do the same as in line 59:

Suggested change

for (const section of sections) {

output += await renderSection(section);

}

output += (await Promise.all(sections.map(section => renderSection(section)))).join('');

wbamberg · 2023-04-04T16:58:06Z

LGTM, just two refactoring opportunities (+ one older comment regarding the (en-US) postfix).

Sorry, I forgot about the paths thing (I remembered much too late to add to this PR!). Much better this way.

caugner

LGTM, just one trailing slash that can probably be removed.

caugner · 2023-04-04T19:11:06Z

kumascript/macros/PWASidebar.ejs

+<%
+
+const sidebar = {
+  sidebarURL: "/docs/Web/Progressive_web_apps/",


Trailing slash:

Suggested change

sidebarURL: "/docs/Web/Progressive_web_apps/",

sidebarURL: "/docs/Web/Progressive_web_apps",

caugner · 2023-04-04T19:13:44Z

@wbamberg Now that this PR is no longer a draft, would you mind updating the PR description to follow our template? 🙌

caugner · 2023-04-05T16:25:39Z

Awesome work, @captainbrosset and @wbamberg! 🎉

Create a PWA sidebar

1701931

github-actions bot added the macros tracking issues related to kumascript macros label Feb 17, 2023

Fix case for sidebar URL

1d9dd64

captainbrosset mentioned this pull request Feb 21, 2023

Add a new display mode How-to page to PWA docs mdn/content#24709

Merged

caugner requested changes Feb 24, 2023

View reviewed changes

captainbrosset mentioned this pull request Feb 27, 2023

Add a new color customization How-to page to PWA docs mdn/content#24925

Merged

caugner added the sidebar/toc Sidebar and table of contents label Mar 2, 2023

caugner changed the title ~~Create a PWA sidebar~~ feat(macros): create a PWA sidebar Mar 2, 2023

wbamberg mentioned this pull request Mar 4, 2023

[PROJECT] Revamp the Progressive Web Apps documentation mdn/mdn#280

Closed

wbamberg mentioned this pull request Mar 28, 2023

[PWA] Add a guide on offline and background operation mdn/content#25305

Merged

wbamberg and others added 5 commits April 3, 2023 11:48

Update kumascript/macros/PWASidebar.ejs

301b902

Co-authored-by: Claas Augner <495429+caugner@users.noreply.github.com>

Update kumascript/macros/PWASidebar.ejs

9b044f2

Co-authored-by: Claas Augner <495429+caugner@users.noreply.github.com>

Fix suggestion

fa543f4

Update for current page set

46aba1c

wbamberg mentioned this pull request Apr 4, 2023

[PWA] PWA reorg mdn/content#25888

Merged

wbamberg marked this pull request as ready for review April 4, 2023 04:08

wbamberg requested a review from caugner April 4, 2023 04:08

caugner requested changes Apr 4, 2023

View reviewed changes

wbamberg added 3 commits April 4, 2023 09:27

Use fully qualified slugs

d93a7fe

Review comments (refactoring)

72a49b5

Formatting

8ac094f

wbamberg requested a review from caugner April 4, 2023 16:57

caugner approved these changes Apr 4, 2023

View reviewed changes

Remove trailing slash

c6e4b77

captainbrosset approved these changes Apr 5, 2023

View reviewed changes

wbamberg merged commit 26e1e35 into mdn:main Apr 5, 2023
10 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(macros): create a PWA sidebar #8238

feat(macros): create a PWA sidebar #8238

wbamberg commented Feb 17, 2023 •

edited

captainbrosset commented Feb 20, 2023

wbamberg commented Feb 20, 2023

captainbrosset commented Feb 21, 2023

estelle commented Feb 21, 2023

wbamberg commented Feb 21, 2023

wbamberg commented Feb 21, 2023 •

edited

caugner Feb 24, 2023

wbamberg commented Apr 4, 2023 •

edited

caugner left a comment

caugner Apr 4, 2023

caugner Apr 4, 2023

wbamberg commented Apr 4, 2023

caugner left a comment

caugner Apr 4, 2023

caugner commented Apr 4, 2023

caugner commented Apr 5, 2023

	sidebarURL: "/docs/Web/Progressive_web_apps/",
	sidebarURL: "/docs/Web/Progressive_web_apps",

feat(macros): create a PWA sidebar #8238

feat(macros): create a PWA sidebar #8238

Conversation

wbamberg commented Feb 17, 2023 • edited

Summary

Problem

Solution

Screenshots

Before

After

How did you test this change?

captainbrosset commented Feb 20, 2023

wbamberg commented Feb 20, 2023

captainbrosset commented Feb 21, 2023

estelle commented Feb 21, 2023

wbamberg commented Feb 21, 2023

wbamberg commented Feb 21, 2023 • edited

caugner Feb 24, 2023

Choose a reason for hiding this comment

wbamberg commented Apr 4, 2023 • edited

caugner left a comment

Choose a reason for hiding this comment

caugner Apr 4, 2023

Choose a reason for hiding this comment

caugner Apr 4, 2023

Choose a reason for hiding this comment

wbamberg commented Apr 4, 2023

caugner left a comment

Choose a reason for hiding this comment

caugner Apr 4, 2023

Choose a reason for hiding this comment

caugner commented Apr 4, 2023

caugner commented Apr 5, 2023

wbamberg commented Feb 17, 2023 •

edited

wbamberg commented Feb 21, 2023 •

edited

wbamberg commented Apr 4, 2023 •

edited