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 ready!

Name	Link
🔨 Latest commit	d55fbb1
🔍 Latest deploy log	https://app.netlify.com/sites/typescript-eslint/deploys/665efca61048b60008554b45
😎 Deploy Preview	https://deploy-preview-9024--typescript-eslint.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (🟢 up 1 from production) Accessibility: 100 (no change from production) Best Practices: 92 (no change from production) SEO: 98 (no change from production) PWA: 80 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit d55fbb1. 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 31 targets

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

---

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.

[JoshuaKGoldberg]

@Josh-Cena that is a fantastic point. I'm now realizing that the "What About ..." pages are the only ones under Troubleshooting that aren't actually "troubleshooting" content... and both get less and less relevant over time. I pushed them down into Users.

I also more formally split the FAQs into a page per area (ESLint, frameworks, JS, TS).

[bradzacher]

PERSONALLY I don't love having valuable content on a page that's accessible via an expandable header.
EG /troubleshooting/faqs is accessible via the FAQs menu item and that menu item is expandable.
It's a confusing UX paradigm, IMO. Cos if I click on the arrow to expand then I see no menu item for "general FAQ"s

I think that either:
a) there should only be cursory information in the link for the expandable item. eg /users and /developers just has a summary of the section. Or
b) there should be a concrete menu item for that page so that it shows up in the expanded list. EG if you click on the "Getting Started" heading it is also available as the "Quickstart" sub-item.

I personally find all the time that I click the arrow and don't find what i'm looking for - only to realise that I actually wanted to click 10px to the left on the item itself.
The UX confusion is that so many sites treat an expandable section header purely as a button to expand the section. Others also do what docusaurus does and treats it as its own menu item AND as a button to expand the section.

I hate it, personally!
One other point against it. On mobile if you click on the heading instead of the arrow (which is really easy to fat finger and do accidentally) then the entire menu disappears and you see the page. So if you were trying to view a sub-menu item you need to re-open the menu again.

I do this all the time on my phone and I hate it. For example I've done this a few times:

1. open typescript-eslint.io
2. tap the hamburger to open the menu
3. tap docs
4. the menu disappears and I'm on the "getting started" page
5. tap the hamburger
6. tap to expand the "contributing" section
7. accidentally fat-fingered it and tapped the heading instead of the arrow
8. the menu disappears and I'm on the "contributing" page
9. tap the hamburger a 3rd time
10. now I can get to the sub items

Super clunky UX - I hate it.

---

So I'd suggest adding a "General" item beneath FAQs which allows you to see the "general FAQs".