[Bug]: docs confusion - deprecated presets

[dandv]

Version

29.2.0

Steps to reproduce

The documentation at https://kulshekhar.github.io/ts-jest/docs/getting-started/presets#the-presets states

⚠️ The list of preset below is now deprecated in favor of util functions.

Expected behavior

Should that be "presets" (plural)?

What exactly does that mean?

How can the "util functions" be used?

Actual behavior

https://kulshekhar.github.io/ts-jest/docs/getting-started/presets#basic-usage then says,

// Replace ts-jest with the preset you want to use from the above list

If all presets in the list are deprecated, should that comment be updated?

Also, is the example at https://kulshekhar.github.io/ts-jest/docs/guides/esm-support#use-esm-presets outdated? It uses preset: 'ts-jest/presets/default-esm', // or other ESM presets.

I'm just trying to use the latest ESM preset that supports Top-Level Await, with least hassle.

[ahnpnl]

I put the link to Advanced section, but it seems like not too obvious. Do you have any suggestions about wording to instruct to read Advanced section.

Or maybe we should even rename Advanced to be something else.

Other places indeed need to be updated with util functions

[ahnpnl]

I saw Docusaurus at https://docusaurus.io/docs/migration/v3 has a block "HOW TO UPGRADE". I'm thinking about adding similar block, like "HOW TO MIGRATE"

[dandv]

Do you have any suggestions about wording to instruct to read Advanced section.

If I understand correctly that presets should be used by calling functions like createDefaultEsmPreset as shown in the example at the very bottom of the page, then my suggestions would be to:

1. Start the Presets page with "The current best practice for using presets is to call one of the utility functions below to create (and optionally extend) presets. Legacy presets are listed at the bottom of the page."
2. Move the list of utility function from "Advanced" section to the top after the paragraph above, along with the example. The example should work out of the box for TypeScript + TLA, keeping in mind that most users really don't care about transforms or ESM or whatever is going on under the hood. They just want Jest to work TypeScript files, to support Top Level Await, and to not have to change their import syntax to accommodate ESM/TLA in tests.
3. For users who do care, the section can then explain that example and these utility functions:
   • what is the advantage of using this much more verbose syntax instead of the simple presets?
   • what does .transform do?
   • what other properties are available on the object returned by create...Preset()?
   • what other keys besides transform must, or should, be used? (link to reference page)
4. Rename the "Basic usage" section to "Legacy preset usage".
5. Move the table of presets under this Legacy section.

[ahnpnl]

I also looked at Jest documentation, specificly API page. I think we can also create kind of like table of content at the top of the page which contains function names. Each item in table of content will link to the description as well as explanation below