Various minor tweaks for website

[clemyan]

What's the problem this PR addresses?

There are a number of build tooling and minor problems with the website. (Listed below)

How did you fix it?

Maintainers: I have marked this as draft for now due to the Questions/TODOs/TBDs. Most of these I just implemented the fix that I think is the most straightforward/reasonable. Feel free to edit/merge/cherry-pick anything here as you see fit.

• The bundled TS type check is bugged (e.g. xterm-headless is reported as "no types")
  • Fix: prioritize type entrypoints (types and typings fields in pacakge.json, types condition) instead of normal (JS) entrypoints when resolving the package.
  • On second thought I think it is better to split this to another PR (docs: fix package bundled TS type check #5867)
• Building the website fails on Windows due to quirks of child_process on Windows
  • Fix: use cross-spawn, which @yarnpkg/core already depends on
• There are a number of unused files/assets/patches/dependencyMetas
  • Fix: delete them
• The README is the default one generated by Docusuarus
  • Fix: Update it to have slightly more useful info
• There are a number of broken links, as reported by docusaurus during build
  • In particular, the Release Workflow was not ported to the new website.
  • Fix: port the Release Workflow page from the old website
  • Fix: Delete the extraneous "Publishing" page, for now
  • Fix: change broken links to new URLs
  • Question: What is the "Publishing" page? Is it supposed to be a re-written Release Workflow page?
• There are also a number of broken links from other places in this repo
  • There are a total of 12 broken links (404 or not the intended page)
    • 1 of them is to https://yarnpkg.com/advanced/sherlock, where there is no short-term resolution (see [Bug?]: Sherlock Playground returns "Internal Server Error" #5859)
    • 2 of them are to https://yarnpkg.com/api, see below
    • 4 of them are in old blog posts. Let's leave them be
    • Fix: Fix the other 5
  • There are a few links to https://yarnpkg.com/features/zero-installs, which 301-redirects to https://yarnpkg.com/features/caching#zero-installs
    • 2 of them are in old blog posts / CHANGELOG. Let's leave them be
    • Fix: Change the others to the canonical URL
  • There are a few links to package pages like https://yarnpkg.com/package/eslint, which 301-redirects to https://yarnpkg.com/package?name=eslint
    • Question: Should we change those to the canonical URLs
• There is an extraneous TOC block in the Rulebook, a remnant of the old Gatsby-based website
  • Fix: Remove it. Docusaurus adds a right sidebar/"On this page" block automatically
• The output during build is quite excessive. In particular, our own commandLineHighlight plugin is spewing multi-line "fail to parse" errors onto the console, which interferes with docusaurus' own progress bar
  • Fix: reduce the commandLineHighlight plugin output to only display the command line that failed to parse
  • Question: This a not a very elegant solution. Are there better alternatives?
  • I have an idea for a better solution. Will be a separate PR
• There are two warnings during build:
  • webpack warns js-yaml on using buffer
  • Fix: Explicitly disable the buffer polyfill as suggested
  • autoprefixer warns src/css/custom.css on using text-decoration-skip CSS property
  • Fix: Use text-decoration-skip-ink instead as suggested
• Add a dropdown to the navbar that links to the old websites
  • Question: Should we use versioned docs for v4+?
• TBD: While generating the CLI docs, run the CLI in JS instead of via the OS shell to avoid spawning a terminal window
• TBD: The API reference is completely removed. What should we do about it?
• TBD: Should we update caniuse-lite as suggested? Should we do it regularly?

Closes #5667 (supersedes)
Closes #5860 (supersedes)
Closes #5894 (supersedes)
Fixes #5707
Fixes #5805
Fixes #5832
Fixes #5861
Fixes #5869
Fixes #5926

Checklist

• I have read the Contributing Guide.

• I have set the packages that need to be released for my changes to be effective.

• I will check that all automated PR checks pass before the PR gets reviewed.

[arcanis]

Thanks for looking into all that 🙏

Question: What is the "Publishing" page? Is it supposed to be a re-written Release Workflow page?

Yes! I wanted to rework the release workflow so I didn't immediately port the page, but didn't find the time and forgot to add it back. It's fine to replace publishing by the old page.

Question: This a not a very elegant solution. Are there better alternatives?

Ideally we shouldn't have commands that fail to parse - are they legit bugs?

Question: Should we use versioned docs for v4+?

I tend to prefer having one single source of truth (outside of when we completely replace the old documentation, like v1 -> v2 or v3 -> v4), to avoid people reading the wrong one and to make it easier to fix our own mistakes. That being said, having "this feature got added in X.Y" markers would be useful. Perhaps that'd be something for Clipanion?

TBD: The API reference is completely removed. What should we do about it?

Typedoc was a little complex and I didn't have time to port it / restyle it, so I put it aside. It can be added back, but perhaps there's a simpler API documentation generator we could use? Or even a Docusaurus plugin?

[clemyan]

Yes! I wanted to rework the release workflow so I didn't immediately port the page, but didn't find the time and forgot to add it back. It's fine to replace publishing by the old page.

In that case I will proceed with the original title and URL features/release-workflow to avoid having to add a redirect

Ideally we shouldn't have commands that fail to parse - are they legit bugs?

Most of them are in blog posts or exposition where a placeholder arg (e.g. <name>) or a shell line is used. There are 2 in the migration guide regarding unimplemented commands.

[clemyan]

Once we resolve the 2 outstanding questions I will mark this as ready. The TBDs will take some more time to investigate so let's not get blocked on them.

[clemyan]

Ideally we shouldn't have commands that fail to parse - are they legit bugs?

Most of them are in blog posts or exposition where a placeholder arg (e.g. ) or a shell line is used. There are 2 in the migration guide regarding unimplemented commands.

I have an idea for a better solution, but it is more involved and this PR is intended to be an aggregation of "low-hanging fruits" so as not to flood the PR queue. I'll make a separate PR.

I tend to prefer having one single source of truth (outside of when we completely replace the old documentation, like v1 -> v2 or v3 -> v4), to avoid people reading the wrong one and to make it easier to fix our own mistakes.

I think having just stable and master (in addition to v1 and v3 docs) already makes it much better, but looks like it'll take some effort. Again, separate PR if and when I find the time (or someone else can take over).

That being said, having "this feature got added in X.Y" markers would be useful. Perhaps that'd be something for Clipanion?

I think adding notes manually when we update docs for new features is suffice for now. If and when Clipanion get this feature we can integrate it.

Typedoc was a little complex and I didn't have time to port it / restyle it, so I put it aside. It can be added back, but perhaps there's a simpler API documentation generator we could use? Or even a Docusaurus plugin?

docusaurus-plugin-typedoc-api looks promising. Again, separate PR.

---

That leaves

There are a few links to package pages like https://yarnpkg.com/package/eslint, which 301-redirects to https://yarnpkg.com/package?name=eslint

Question: Should we change those to the canonical URLs

For now, I'll leave those alone. I'll rebase and mark this PR as ready. If maintainers think we should update them I can do it.

---

/ping @arcanis

[arcanis]

Thanks a lot!