docs: split troubleshooting into granular sections

[JoshuaKGoldberg]

PR Checklist

• Addresses an existing open issue: fixes Docs: Separate FAQs into discrete sections #8926
• That issue was marked as accepting prs
• Steps in Contributing were taken

Overview

• Move around the FAQs into a few new sections
• Move around sidebar.base.js contents so the sidebar isn't now bigger than before
• Add notes on followup issues we can file to fill out those new FAQs (💡!)
• Add redirects so old user-facing code links included in code still work
  • Get irritated by having to do this and file Docs: Consider using a URL shortener for links printed by code #9023

Before	After

💖

[typescript-eslint]

Thanks for the PR, @JoshuaKGoldberg!

typescript-eslint is a 100% community driven project, and we are incredibly grateful that you are contributing to that community.

The core maintainers work on this in their personal time, so please understand that it may not be possible for them to review your work immediately.

Thanks again!

---

🙏 Please, if you or your company is finding typescript-eslint valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/typescript-eslint.

[netlify]

❌ Deploy Preview for typescript-eslint failed.

Name	Link
🔨 Latest commit	eebba86
🔍 Latest deploy log	https://app.netlify.com/sites/typescript-eslint/deploys/665a2679d49ad800083157c1

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit eebba86. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 17 targets

• nx run-many --target=lint --parallel --exclude eslint-plugin
• nx run-many --target=typecheck --parallel
• nx test utils --coverage=false
• nx test type-utils --coverage=false
• nx run types:build
• nx test eslint-plugin-internal --coverage=false
• nx test rule-schema-to-typescript-types --coverage=false
• nx test scope-manager --coverage=false
• nx test repo-tools --coverage=false
• nx test parser --coverage=false
• nx test ast-spec --coverage=false
• nx test visitor-keys --coverage=false
• nx test typescript-eslint --coverage=false
• nx run integration-tests:test
• nx run repo-tools:postinstall-script
• nx run repo-tools:generate-configs
• nx run-many --target=build --parallel --exclude=website --exclude=website-eslint

---

Sent with 💌 from NxCloud.

[JoshuaKGoldberg]

🤔 I'm on the fence of whether this deserves its own page. I think it could be moved to its own section in FAQs.mdx. Is there anything else we'd want to have here?

I was tempted to include typed linting .js info, but that's already covered in Typed Linting.

I'm leaning strongly towards this change (moving these two FAQs out) so we can reduce the size of the Troubleshooting portion of the sidebar.

[kirkwaiblinger]

I think it's worth its own page! See also #8955 (comment)... maybe this is an opportunity to throw in an additional sentence or two that plenty of rules will have no effect on js files, but a few will enforce illegal syntax and must be disabled. And type-aware rules actually can work in js files.

[JoshuaKGoldberg]

Yeah! Great. +1. I think that'd be an excellent followup to this (I suspect the discussion over how to phrase the .js recommendations might get long).

[kirkwaiblinger]

Overall looks sensible to me! A few teensy nits to resolve, and then a bunch of broken links, it looks like (including when using the search bar). But I'm assuming those are enforced by CI, rather than human eyes.

[bradzacher]

This is going to break all of our historical links isn't it 😭

Maybe we need error code short URLs to make this easier huehuehue

[JoshuaKGoldberg]

It shouldn't with this redirects config! I really hope it doesn't. That'd be a bug if it does.

// in docusaurus.config.mts > redirects
    {
      from: '/troubleshooting',
      to: '/troubleshooting/faqs',
    },

But yeah strong +1 to error code short URLs.

[Josh-Cena]

I have a general comment about the hierarchy. "TSLint" and "Formatting" are "FAQs" but not really "Troubleshooting". This makes me think if it shouldn't look like:

faqs
  tslint
  formatting
  troubleshooting
    index
    working-with-javascript
    typed-linting
      index
      monorepos
      performance

Btw I strongly recommend using faqs/index.mdx instead of FAQs.mdx. Makes it easier to look at the hierarchy.