Add grouped guides functionality

[colleenmcginnis]

Proposed approach

This PR proposes a way to group guides. @katydecorah can you take an initial look at this proposal that came out of last week's The Write Stuff session and let me know what you think of the direction?

Contributor experience

The proposed approach works like this:

• To create a group of guides, create a directory in the pages/({section}/)guides/ folder.
• This directory must include an index.md file and its frontmatter should include group: true.

• Any page tagged with group: true will automatically include a GuideGroupIndex. This is a table of contents of all the guides in the group.
• In all other Markdown files in the group, specify the order in which the guides should appear in the sidebar (and in the guide group index) by including groupOrder: {number} in the frontmatter for each page.

How existing functionality/components are affected

Several changes are necessary:

• Update the structure of the navigation Batfish helper that's used to pass data to various components when building the site navigation.
  • Accommodate another level in hierarchy. Create a list of all the guide groups for reference. Then when iterating through the organized pages, if the page is a part of a guide group (has groupOrder in the frontmatter), get the path of the group it belongs to and set that as the parent path. Then use that path to get the title of the group from the list of all guide groups you created earlier and set it as parent title.
  • Sort grouped guides by groupOrder. Add the sorted list to a new subPages property for each group index page.
  • Pass new frontmatter properties. Pass the new group and groupOrder frontmatter items to be included in the resulting navigation data. (I also added description so it can be used in the GuideGroupIndex and NextPrevPage components detailed below).
• Update the NavigationAccordion component to use this updated data including displaying an additional level of hierarchy.
  • Create a list of grouped guides. Display that list of grouped guides if either the parent is active or another guide in the group is active.
  • Update active state of group index. In addition to the title of the active page being highlighted blue in the sidebar, we also bold the the title of the active group.
• Update the PageLayout component to use updated hierarchy in Breadcrumbs.
  • Add a grandparent item in addition to parent item where appropriate. If the page is part of a group of guides, include another level between the content type and the current page.

New components with additional context

It also introduces two new components that accompany this change:

• GuideGroupIndex: This component creates a table of contents to add to the page layout when the frontmatter includes group: true. This pulls in the title and description from the frontmatter of all pages in the same directory (group of guides). Looks like:

• NextPrevPage: This component adds a next and previous link to the bottom of all pages with a groupOrder in the frontmatter. This is meant to emphasize that these guides are meant to be read in the order. Looks like:

How to test

TBD

QA checklist

• No errors logged to console.
• Accessibility score in Chrome DevTools Audit/Lighthouse is 100% with Lighthouse version: #.#.#.
• Component is accessible at mobile-size viewport.
• Component is accessible at tablet-size viewport.
• Component is accessible at laptop-size viewport.
• Component is accessible at big-monitor-size viewport.

Open the test cases app locally on:

• Chrome, no errors logged to console.
• Firefox, no errors logged to console.
• Safari, no errors logged to console.
• Edge, no errors logged to console.
• Mobile Safari, no errors logged to console.
• Android Chrome, no errors logged to console.

Before merge

• Add entry to CHANGELOG.md to describe changes.
• If updating dependencies or creating a release, run npx browserslist@latest --update-db to update the browser data and commit any changes to package-lock.json.

cc @mapbox/docs @abhishek1508

[katydecorah]

Exciting! Overall, I think the direction is great. @colleenmcginnis I have a few initial questions:

• Do GuideGroupIndex and NextPrevPage need to be a standalone component or could it be inside page-layout directory? I guess the question is: do we ever want to encourage the use of these components outside of PageLayout?
• Will NextPrevPage appear for all guides or just grouped guides?
• Should we disable Feedback on pages with GuideGroupIndex?
• Would you mind adding a grouped guides demo to the the catalog site?

[colleenmcginnis]

do we ever want to encourage the use of these components outside of PageLayout?

I can't think of any uses outside of PageLayout. I can fold them into the PageLayout component.

Will NextPrevPage appear for all guides or just grouped guides?

I'm open to opinions. Not all products have guides ordered in a chronological way, but maybe that doesn't really matter.

Should we disable Feedback on pages with GuideGroupIndex?

I thought about this too! I thought about maybe making it full-width, but in The Write Stuff we talked about maybe wanting to enable contributors to provide some custom content on this page in addition to the table of contents type content to explain how concepts relate to each other. I could be convinced either way on the inclusion of Feedback.

Would you mind adding a grouped guides demo to the the catalog site?

Yes!! This was going to be my next step after getting your initial reaction. :)

[katydecorah]

do we ever want to encourage the use of these components outside of PageLayout?

I can't think of any uses outside of PageLayout. I can fold them into the PageLayout component.

Great, that's my recommendation. In this way our design system is a little more opinionated to help keep our sites consistent. But I think we can still have all the tests and examples we need to make sure each subcomponent is covered.

Will NextPrevPage appear for all guides or just grouped guides?

I'm open to opinions. Not all products have guides ordered in a chronological way, but maybe that doesn't really matter.

This distinction between chronological guides and grouped guides makes sense. It sounds like NextPrevPage is ideal for just grouped guides, at least for now!

Should we disable Feedback on pages with GuideGroupIndex?

I thought about this too! I thought about maybe making it full-width, but in The Write Stuff we talked about maybe wanting to enable contributors to provide some custom content on this page in addition to the table of contents type content to explain how concepts relate to each other. I could be convinced either way on the inclusion of Feedback.

That makes sense! I'm in favor for keeping Feedback on these pages for now!

Would you mind adding a grouped guides demo to the the catalog site?

Yes!! This was going to be my next step after getting your initial reaction. :)

🤗

[colleenmcginnis]

Ok @katydecorah this is ready for a closer look! (but not urgent)

[colleenmcginnis]

@katydecorah I'm not sure why the tests are still failing. They pass locally for me...

[katydecorah]

@colleenmcginnis The tests seem to be pointing at this 404 path. Want to try removing this line?

dr-ui/src/helpers/batfish/__tests__/sitemap.test.js

Line 126 in a084f24

'https://mapbox.github.io/dr-ui/404',

If it continues to give grief, then it's likely an issue with the sitemap tests and I'll look into it and fix in a new PR.

Also want to note, that the sitemap test will only run if the catalog site has been built and created the sitemap. Which can be tricky to test locally, since these test will only run if you had recently run npm run start-docs. We may need to rethink the sitemap tests so they are less tricky 🤔

[colleenmcginnis]

Now it fails locally, but passes here!

Which can be tricky to test locally, since these test will only run if you had recently run npm run start-docs.

I did do that recently! 💡

[katydecorah]

Now it fails locally, but passes here!

Ugh! I'll look into smoothing this out.

[katydecorah]

This is looking so good! I left several suggestions and questions. Let me know if you want to talk through anything.

[katydecorah]

Do we have tests for this function?

[katydecorah]

I'm also wondering if we should move this to the batfish navigation helper to take pressure off the frontend. For example, maybe we could add groups to the navigation object:

{
  "navTabs": {...},
  "hierarchy": {...},
  "groups": {
    "/dr-ui/guides/grouped-guides/": [ /* array of objects of page data: title, url, description */]
  }
}

Then we can use something like the findParentPath() function then navigation.groups[parentPath] to return the list of subpages for the group.

[colleenmcginnis]

I'm definitely open to something like this, but was feeling like I was in over my head with the batfish helpers! Maybe this is something we could pair on next week?

[katydecorah]

Let's pair!!

[katydecorah]

Per chat today, I got this wrong! You are already using the dataset; no need to offload to a batfish helper, but we maybe able to reduce some lines of code if we passed switchedNavigation from PageLayout > Content > GroupedGuidesIndex.

[colleenmcginnis]

Note to self: try using switchedNavigation in place of navigation here to minimize complexity of getSubPages function in page layout utils.js.

[colleenmcginnis]

I wasn't able to figure out how to use switchedNavigation because it doesn't include hierarchy, which is used getSubPages. Let me know if I'm missing something!

[colleenmcginnis]

I wasn't able to figure out how to use switchedNavigation because it doesn't include hierarchy, which is used getSubPages. Let me know if I'm missing something!

[katydecorah]

This looks excellent, Colleen! Before you merge, I recommend creating a beta release and then testing the release in iOS or Android docs repository. This will allow you to test with real data and make updates to this PR if you find any bugs, instead of creating a release and then having to follow-up with a patch release in another PR.

Steps for a beta release:

1. From this branch, manually update the version in package.json and package-lock.json (maybe 4.1.0-beta.0).
2. Commit your changes.
3. Run npm run build.
4. Then cd pkg and mbx npm publish

To test a new change committed to this branch, follow the same steps but increment the last number - .0. So the next release from this branch 4.1.0-beta.1.