docs: update website

I was intending on clarifying #885, but then just kept editing.

docs/README.md

@@ -18,7 +18,7 @@ Bundle your TypeScript library with no config, powered by [esbuild](https://gith
 
 ## What can it bundle?
 
-Anything that's supported by Node.js natively, namely `.js`, `.json`, `.mjs`. And TypeScript `.ts`, `.tsx`. [CSS support is experimental](#css-support).
+Anything that's supported by Node.js natively, namely `.js`, `.json`, `.mjs`; TypeScript `.ts`, `.tsx`; and experimental [CSS support](#css-support).
 
 ## Install
 
@@ -191,11 +191,11 @@ tsup index.ts --dts
 
 This will emit `./dist/index.js` and `./dist/index.d.ts`. When emitting multiple [bundle formats](#bundle-formats), one declaration file per bundle format is generated. This is required for consumers to get accurate type checking with TypeScript. Note that declaration files generated by any tool other than `tsc` are not guaranteed to be error-free, so it's a good idea to test the output with `tsc` or a tool like [@arethetypeswrong/cli](https://www.npmjs.com/package/@arethetypeswrong/cli) before publishing.
 
-If you have multiple entry files, each entry will get a corresponding `.d.ts` file. So when you only want to generate declaration file for a single entry, use `--dts <entry>` format, e.g. `--dts src/index.ts`.
+If you have multiple entry files, each entry will get a corresponding `.d.ts` file. So when you only want to generate declaration file for a single entry, use `--dts <entry>` format, e.g., `--dts src/index.ts`.
 
 Note that `--dts` does not resolve external (aka in `node_modules`) types used in the `.d.ts` file, if that's somehow a requirement, try the experimental `--dts-resolve` flag instead.
 
-Since tsup version 8.0.0, you can also use `--experimental-dts` flag to generate declaration files. This flag use [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) to generate declaration files, which is more reliable than the previous `--dts` flag. It's still experimental and we are looking for feedbacks.
+Since tsup version 8.0.0, you can also use `--experimental-dts` flag to generate declaration files. This flag use [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) to generate declaration files, which is more reliable than the previous `--dts` flag. It's still experimental, and doesn't support all of the options of the standard `--dts` flag. Please share your feedback!
 
 To use `--experimental-dts`, you would need to install `@microsoft/api-extractor`, as it's a peer dependency of tsup:
 
@@ -211,13 +211,9 @@ The `--dts-only` flag is the equivalent of the `emitDeclarationOnly` option in `
 
 #### Generate TypeScript declaration maps (.d.ts.map)
 
-TypeScript declaration maps are mainly used to quickly jump to type definitions in the context of a monorepo (see [source issue](https://github.com/Microsoft/TypeScript/issues/14479) and [official documentation](https://www.typescriptlang.org/tsconfig/#declarationMap)).
+TypeScript declaration maps are used to jump to the actual source instead of declaration files (see the [source issue](https://github.com/Microsoft/TypeScript/issues/14479) and [official documentation](https://www.typescriptlang.org/tsconfig/#declarationMap)).
 
-They should not be included in a published NPM package and should not be confused with sourcemaps.
-
-[Tsup is not able to generate those files](https://github.com/egoist/tsup/issues/564). Instead, you should use the TypeScript compiler directly, by running the following command after the build is done: `tsc --emitDeclarationOnly --declaration`.
-
-You can combine this command with Tsup [`onSuccess`](https://tsup.egoist.dev/#onsuccess) callback.
+[tsup is not able to generate those files](https://github.com/egoist/tsup/issues/564). Instead, you should use the TypeScript compiler directly, by running the following command after the build is done: `tsc --emitDeclarationOnly --declaration`. If you want to run this as part of your tsup invocation, you can leverage the [`onSuccess`](https://tsup.egoist.dev/#onsuccess) option.
 
 ### Generate sourcemap file
 
@@ -235,7 +231,7 @@ If you want to inline sourcemap, you can try:
 tsup index.ts --sourcemap inline
 ```
 
-> Warning: Note that inline sourcemap is solely used for development, e.g. when developing a browser extension and the access to `.map` file is not allowed, and it's not recommended for production.
+> Warning: Note that inline sourcemaps are solely used for development, e.g., for when developing a browser extension and the access to the `.map` file is not allowed, and it's not recommended for production.
 
 > Warning: Source map is not supported in `--dts` build.
 
@@ -269,7 +265,7 @@ dist
 
 Read more about [`esm` support in Node.js](https://nodejs.org/api/esm.html#esm_enabling).
 
-If you don't want extensions like `.mjs` or `.cjs`, e.g. you want your library to be used in a bundler (or environment) that doesn't support those, you can enable `--legacy-output` flag:
+If you don't want extensions like `.mjs` or `.cjs`, e.g., you want your library to be used in a bundler (or environment) that doesn't support those, you can enable `--legacy-output` flag:
 
 ```bash
 tsup src/index.ts --format esm,cjs,iife --legacy-output
@@ -509,29 +505,29 @@ Additionally, if you want type checking at build time, you can enable `--dts`, w
 
 ### CSS support
 
-esbuild has [experimental CSS support](https://esbuild.github.io/content-types/#css), and tsup allows you to use PostCSS plugins on top of native CSS support.
+esbuild has [experimental CSS support](https://esbuild.github.io/content-types/#css), and tsup allows you to use PostCSS plugins on top of it.
 
-To use PostCSS, you need to install PostCSS:
+To use PostCSS, you'll need to separately install PostCSS:
 
 ```bash
-npm i postcss -D
+npm install -D postcss
 # Or Yarn
-yarn add postcss --dev
+yarn add --dev postcss
 ```
 
-..and populate a `postcss.config.js` in your project
+...and populate a `postcss.config.js` in your project
 
 ```js
-module.exports = {
-  plugins: [require('tailwindcss')(), require('autoprefixer')()],
-}
+module.exports = /** @satisfies {import('postcss-load-config').Config} */ ({
+  plugins: [require('postcss-preset-env')],
+})
 ```
 
 ### Metafile
 
 Passing `--metafile` flag to tell esbuild to produce some metadata about the build in JSON format. You can feed the output file to analysis tools like [bundle buddy](https://www.bundle-buddy.com/esbuild) to visualize the modules in your bundle and how much space each one takes up.
 
-The file outputs as `metafile-{format}.json`, e.g. `tsup --format cjs,esm` will generate `metafile-cjs.json` and `metafile-esm.json`.
+The file outputs as `metafile-{format}.json`, e.g., `tsup --format cjs,esm` will generate `metafile-cjs.json` and `metafile-esm.json`.
 
 ### Custom esbuild plugin and options