Update docs (close #583)

packages/docs/src/content/docs/explanations/entry-files.md

@@ -32,38 +32,36 @@ entry files. Here's the default configuration in full:
 }
 ```
 
-Next to the default locations, or the entry file patterns configured by you,
-Knip also looks for `entry` files in other places. All of this is done for each
-workspace separately.
+Next to the default locations, Knip looks for `entry` files in other places. In
+a monorepo, this is done for each workspace separately.
 
 The values you set override the default values, they are not merged.
 
+## Plugins
+
+Plugins often add entry files. For instance, if the Remix, Storybook and Vitest
+plugins are enabled in your project, they'll add additional entry files. See
+[the next page about plugins][2] for more details about this.
+
 ## Scripts in package.json
 
-The `main`, `bin`, and `exports` fields may contain entry files. The `scripts`
-are also parsed to find entry files and dependencies. See [Script Parser][2] for
-more details.
+The `package.json` is scanned for entry files. The `main`, `bin`, and `exports`
+fields may contain entry files. The `scripts` are also parsed to find entry
+files and dependencies. See [Script Parser][3] for more details.
 
 ## Ignored files
 
 Knip respects `.gitignore` files. By default, ignored files are not added as
-entry files. This behavior can be disabled by using the [`--no-gitignore`][3]
+entry files. This behavior can be disabled by using the [`--no-gitignore`][4]
 flag on the CLI.
 
-Glob patterns can also be negated, for example:
-
-```json
-{
-  "entry": ["lib/entry-*.js", "!lib/entry-excluded.js"]
-}
-```
-
 ## Configuring project files
 
-See [configuring project files][4] for guidance with the `entry`, `project` and
+See [configuring project files][5] for guidance with the `entry`, `project` and
 `ignore` options.
 
 [1]: ../overview/configuration.md#defaults
-[2]: ../features/script-parser.md
-[3]: ../reference/cli.md#--no-gitignore
-[4]: ../guides/configuring-project-files.md
+[2]: ./plugins.md
+[3]: ../features/script-parser.md
+[4]: ../reference/cli.md#--no-gitignore
+[5]: ../guides/configuring-project-files.md

packages/docs/src/content/docs/explanations/why-use-knip.md

@@ -38,7 +38,13 @@ start? Knip contains a lot of standards and heuristics to search for things that
 can be deleted. Knip is not without flaws. But even a list of results with a few
 false positives is many times better and faster than trying to do it manually.
 
-Knip not only finds unused things, it can also [fix issues][2]!
+:::tip
+
+Knip not only finds unused things, it can also [fix issues][2]! Use Knip next to
+a linter like ESLint or Biome: after removing unused variables inside files,
+Knip might find even more unused code. Rinse and repeat!
+
+:::
 
 ## Comprehensive
 
@@ -54,18 +60,18 @@ synergy:
 - This approach is amplified in a monorepo setting. In fact, files and internal
   dependencies can recursively reference each other (across workspaces).
 
-The disadvantages of this strategy are not to be dismissed: increased complexity
-and less performance. In this early phase of the project completeness and
-correctness are valued over speed. Not in the least because the speed of
-automating this is still many times faster than the manual process. Both
-complexity and performance can be optimized further down the road.
-
 ## Greenfield or Legacy
 
 Installing Knip in greenfield projects ensures the project stays neat and tidy
 from the start. Add it to your CI workflow and prevent any regressions from
 entering the codebase.
 
+:::tip
+
+Use Knip in a CI environment to prevent future regressions.
+
+:::
+
 In large and/or legacy projects, Knip may report false positives and require
 some configuration. Yet it can be a great assistant when cleaning up parts of
 the project or doing large refactors. Again, even a list of results with a few

packages/docs/src/content/docs/features/auto-fix.mdx

@@ -83,8 +83,9 @@ Unused dependencies are removed from `package.json`:
 
 ## Post-fix
 
-- You may want to run tools like `eslint --fix` or `prettier --write` to fix the
-  remaining issues.
+- You may want to run tools like `eslint --fix` or `biome lint --apply` to fix
+  the remaining issues inside files. This may result in more deleted code, and
+  Knip may then find more unused code. Rinse and repeat!
 - Verify changes in `package.json` and update dependencies using your package
   manager:
 

packages/docs/src/content/docs/features/production-mode.md

@@ -40,10 +40,17 @@ Here's what's included in production mode:
 - Only the `start` and `postinstall` scripts
 - Ignore exports with the [`@internal` tag][1]
 
+### Notes
+
 The production run does not replace the default run. Depending on your needs you
 can run either of them or both separately. Usually both modes can share the same
 configuration.
 
+To see the difference between default and production mode in great detail, use
+the `--debug` flag and inspect what entry and project files are used, and the
+plugins that are enabled. For instance, in production mode this shows that files
+such as tests and Storybook files (stories) are excluded from the analysis.
+
 ## Strict Mode
 
 Additionally, the `--strict` flag can be added to:

packages/docs/src/content/docs/features/rules-and-filters.md

@@ -8,10 +8,12 @@ Use rules or filters to customize Knip's output. This has various use cases, a
 few examples:
 
 - Temporarily focus on a specific issue type.
-- You don't want to see `type`, `interface` and `enum` exports reported.
+- You don't want to see unused `type`, `interface` and `enum` exports reported.
 - Specific issue types should be printed, but not counted against the total
   error count.
 
+If you're looking to handle one-off exceptions, also see [JSDoc tags][1].
+
 ## Filters
 
 You can `--include` or `--exclude` any of the reported issue types to slice &
@@ -33,7 +35,7 @@ interested in:
 knip --include files --exclude enumMembers,duplicates
 ```
 
-Also see the [list of issue types][1].
+Also see the [list of issue types][2].
 
 ### Shorthands
 
@@ -67,7 +69,7 @@ Example:
 }
 ```
 
-Also see the [issue types overview][1].
+Also see the [issue types overview][2].
 
 The rules are modeled after the ESLint `rules` configuration, and could be
 extended in the future.
@@ -83,4 +85,5 @@ fine-grained configuration.
   configuration).
 - Filters have shorthands (rules don't have this).
 
-[1]: ../reference/issue-types.md
+[1]: ../reference/jsdoc-tsdoc-tags.md
+[2]: ../reference/issue-types.md

packages/docs/src/content/docs/guides/configuring-project-files.md

@@ -10,33 +10,30 @@ out of Knip.
 
 The key takeaways of this page include:
 
-- Start out by defining targeted `entry` and `project` files (if the defaults
-  aren't good enough).
+- If the defaults need adjustment, define targeted `entry` file patterns.
+- To find unused files, narrow down and add negated `project` patterns.
 - To exclude test and other non-production files, use production mode.
-- Don't use `ignore` to exclude files from the analysis, but add negated `entry`
-  and `project` files instead.
-- Use `ignore` patterns only to exclude issues in matching files from the
-  report.
+- Use `ignore` patterns to exclude issues in matching files from the report.
 
-Let's dive in and take a look at a few examples.
+Let's dive in and expand on all of these.
 
 ## Unused files
 
 Files are reported as unused if they are in the set of project files, but not in
 the set of files resolved from the entry files:
 
 ```
-project files - (entry files + resolved files) = unused files
+unused files = project files - (entry files + resolved files)
 ```
 
-You may want to read the [entry files][1] explainer first to learn how and where
-Knip looks for entry files.
+See [entry files][1] to see where Knip looks for entry files. Read on to learn
+how to fine-tune the sets of entry and project files.
 
 ## Negated patterns
 
-Let's take a look at using negated patterns in `entry` and `project` patterns.
-If there are too many files in the analysis, this could be the first step in
-getting the right files in the analysis.
+Let's take a look at using negated patterns for `entry` and `project` files. If
+you think there are too many files in the analysis, this could be the first step
+in selecting the right files for the analysis.
 
 Say we need to explicitly add route files as entry files, except those starting
 with an underscore. Then we can use a negated pattern like so:
@@ -47,8 +44,8 @@ with an underscore. Then we can use a negated pattern like so:
 }
 ```
 
-If certain files are not part of our project files and are unwantedly reported
-as unused files, we can use negated `project` patterns:
+If certain files are not part of our project source files and are unwantedly
+reported as unused files, we can use negated `project` patterns:
 
 ```json
 {
@@ -84,10 +81,10 @@ In default mode, Knip includes all test files and other non-production files in
 the analysis. To find out what files, dependencies and exports are unused in
 production source files, use [production mode][2].
 
-How NOT to exclude test files from the analysis? To better understand how Knip
-works, here's a list of options that don't work, and why.
+How NOT to exclude test files from the analysis? For a better understanding of
+how Knip works, here's a list of options that don't work, and why:
 
-❌ Don't do this:
+❌   Don't do this:
 
 ```json
 {
@@ -101,7 +98,7 @@ not excluded from the analysis, only their issues are not reported. This also
 hurts performance, since the files are first analyzed, and eventually filtered
 out.
 
-❌ Also don't do this:
+❌   Also don't do this:
 
 ```json
 {
@@ -113,7 +110,7 @@ This won't help if dependencies like Vitest or Ava are listed, because their
 plugins will add test files as entry files anyway, which you can't and shouldn't
 undo or override here.
 
-❌ Also don't do this:
+❌   Also don't do this:
 
 ```json
 {
@@ -129,7 +126,7 @@ This won't help either:
    remains unaffected. You'd need to disable the plugin or override its
    configuration instead.
 
-✅ Do this:
+✅   Do this:
 
 ```shell
 knip --production
@@ -152,9 +149,9 @@ then be excluded in production mode:
 Remember to keep adding the exclamation mark `suffix!` for production file
 patterns.
 
-In large projects where a single configuration for both default and production
-mode gets unwieldy, it might be interesting to consider using a separate
-configuration file for production mode:
+In rare occasions, for large projects where a single configuration for both
+default and production mode gets unwieldy, it might be interesting to consider
+using a separate configuration file for production mode:
 
 ```shell
 knip --production --config knip.production.json