Upgrade Doctocat

[pouretrebelle]

Summary

This resolves a content blowout layout bug on nav component pages - primer/doctocat#739

List of notable changes:

• Upgrading Doctocat to v5.1.1 (releases). Visual changes:
  • No content blowout 🎉
  • Nav in header is now a dropdown (discussed in comments)
  • Larger block margins between text elements (from Update heading.js doctocat#706)
• We have to anchor to PRC v36.11.0 because @react-aria/ssr was removed in v36.12.0 but is still used in doctocat, which has a PRC dependency of ^v36.1.0, where @react-aria/ssr was still a dep. This could be resolved by removing the reliance on the package in Doctocat.
• I upgraded the docs lockfile version to v3 as I can only run this app with node v20 & npm v10. This is backwards compatible to npm v7 which is the minimum specified engine so shouldn't be a problem.

Steps to test:

1. Open nav pages on review app

Contributor checklist:

• All new and existing CI checks pass
• Tests prove that the feature works and covers both happy and unhappy paths
• Any drop in coverage, breaking changes or regressions have been documented above
• New visual snapshots have been generated / updated for any UI changes
• All developer debugging and non-functional logging has been removed
• Related issues have been referenced in the PR description

Reviewer checklist:

• Check that pull request and proposed changes adhere to our contribution guidelines and code of conduct
• Check that tests prove the feature works and covers both happy and unhappy paths
• Check that there aren't other open Pull Requests for the same update/change

Screenshots:

Before	After

[changeset-bot]

⚠️ No Changeset found

Latest commit: 26a8aba

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

🟢 No design token changes found

[github-actions]

⚠️ Visual differences found

Our visual comparison tests found UI differences.

Please review the differences by using the test artifacts to ensure that the changes were intentional.

Artifacts can be downloaded and reviewed locally.

Download links are available at the bottom of the workflow summary screen.

Example:

If the changes are expected, please run npm run test:visual:update-snapshots to replace the previous fixtures.

Review visual differences

[pouretrebelle]

@raytalks can I get your thoughts on this:

PRC in Doctocat was bumped to v36 in v5.1.0 which afaik no primer.style sites have updated to. Upgrading to v36 means that the UnderlineNav has been updated (old, new), which changes the look of the Brand and About links in header. Due to the css setup in the header it defaults to a dropdown menu instead (see screenshots in description).

I tried overloading the header to use the old deprecated nav as a hotfix but couldn't get it working. So the choices here are:

1. Merge this as is, accepting the header will look different between Brand and the rest of primer.style
2. Add a fix to Doctocat which will allow the UnderlineNav to actually render as an underline nav instead of the dropdown. It may still look a shade different to the old version (the deprecated one has slightly different spacing) but I don't think it'd be noticeable. I could also fix the @react-aria/ssr bug at the same time.
3. Close up this pull request and leave the broken layout bug 🤷

N.B. that not doing the second option means that no sites can make Doctocat upgrades without having this issue. Idk if this is a concern for life before nextocat. cc: @dipree

[dipree]

Appreciate the eye to detail, no preference from my side, on product we are quite stuck with doing anything, so, focusing on the new version.

[rezrah]

Let's pin the version here. We want to do this for all dependencies going forward.

Suggested change

	"@primer/gatsby-theme-doctocat": "^5.1.1",
	"@primer/gatsby-theme-doctocat": "5.1.1",

[rezrah]

Can we pin this version too please and avoid wildcards. Guessing it will be 18.2.0 here?

[rezrah]

Option 1 seems okay... reasons being:

• It's using the newer, preferred version of the underline nav pattern
• It's already part of the latest Doctocat release, and that decision (along with the differences it introduces) was presumably made with oversight from Primer LT. I'm also assuming that the upgrade contains various other improvements - particularly around security - that we will benefit from.
• It fixes a major layout issue in our docs right now (SubdomainNavBar overflow)
• Users are already on our site, so finding the Brand tab isn't that important (at this part of the funnel)

I would however, be a much more concerned if product docs moves to this format, as the discoverability of the Brand site would be extremely compromised. cc. @dipree @emilybrick

Perhaps also worth noting that Design LT had previously requested that we avoid introducing notable design differences between the product and marketing documentation sites, and given the prominence of this nav at the top of the page, I'm uncertain if this fall under that scope. That said, there are still enough good reasons for Primer Brand docs to move ahead with this change.

[rezrah]

@pouretrebelle option 2 is also a good shout, because the nav shouldn't be collapsing when the adjacent space is clearely available. If it's not too much work, could you please open the PR and tag in some folks in Primer Design like @emilybrick to validate it? It seems like a bug.