Docs merge for 10.5.0 (#1631)

* Note `skip-ignore` for "Skipping `node_modules`" (#1553)

* Note `skip-ignore` for "Skipping `node_modules`"

* Remove spurious duplication

* update

* revert changes to readme; readme is built from docs/

* more wordsmithing

* more tweaks

Co-authored-by: Andrew Bradley <cspotcode@gmail.com>

* Passing arguments in shebang on Linux (env -S) (#1545)

* Passing arguments in shebang on Linux (env -S)

It is possible to pass arguments into commands in the shebang on Linux using the env(1) -S option.

* fix

* fix

* fix

Co-authored-by: Andrew Bradley <cspotcode@gmail.com>

* link from readme logo to website (#1604)

Co-authored-by: webstrand <webstrand@gmail.com>
Co-authored-by: wmb <sheeit@users.noreply.github.com>

website/docs/how-it-works.md

@@ -16,9 +16,16 @@ Vanilla `node` loads `.js` by reading code from disk and executing it.  Our hook
 
 ## Skipping `node_modules`
 
-By default, **TypeScript Node** avoids compiling files in `/node_modules/` for three reasons:
+By default, ts-node avoids compiling files in `/node_modules/` for three reasons:
 
 1. Modules should always be published in a format node.js can consume
 2. Transpiling the entire dependency tree will make your project slower
 3. Differing behaviours between TypeScript and node.js (e.g. ES2015 modules) can result in a project that works until you decide to support a feature natively from node.js
 
+If you need to import uncompiled TypeScript in `node_modules`, use [`--skipIgnore`](./options#transpilation) or [`TS_NODE_SKIP_IGNORE`](./options#transpilation) to bypass this restriction.
+
+## Skipping pre-compiled TypeScript
+
+If a compiled JavaScript file with the same name as a TypeScript file already exists, the TypeScript file will be ignored.  ts-node will import the pre-compiled JavaScript.
+
+To force ts-node to import the TypeScript source, not the precompiled JavaScript, use [`--preferTsExts`](./options#transpilation).

website/docs/usage.md

@@ -35,14 +35,27 @@ ts-node-cwd script.ts
 console.log("Hello, world!")
 ```
 
-Passing CLI arguments via shebang is allowed on Mac but not Linux.  For example, the following will fail on Linux:
+Passing options via shebang requires the [`env -S` flag](https://manpages.debian.org/bullseye/coreutils/env.1.en.html#S), which is available on recent versions of `env`. ([compatibility](https://github.com/TypeStrong/ts-node/pull/1448#issuecomment-913895766))
 
+```typescript
+#!/usr/bin/env -S ts-node --files
+// This shebang works on Mac and Linux with newer versions of env
+// Technically, Mac allows omitting `-S`, but Linux requires it
 ```
-#!/usr/bin/env ts-node --files
-// This shebang is not portable.  It only works on Mac
+
+To write scripts with maximum portability, [specify all options in your `tsconfig.json`](./configuration#via-tsconfigjson-recommended) and omit them from the shebang.
+
+```typescript
+#!/usr/bin/env ts-node
+// This shebang works everywhere
 ```
 
-Instead, specify all ts-node options in your `tsconfig.json`.
+To test your version of `env` for compatibility:
+
+```shell
+# Note that these unusual quotes are necessary
+/usr/bin/env --debug '-S echo foo bar'
+```
 
 ## Programmatic
 

website/readme-sources/prefix.md

@@ -14,7 +14,7 @@ You can build the readme with this command:
     cd website && yarn build-readme
 -->
 
-# ![TypeScript Node](logo.svg?sanitize=true)
+# [![TypeScript Node](logo.svg?sanitize=true)](https://typestrong.org/ts-node)
 
 [![NPM version](https://img.shields.io/npm/v/ts-node.svg?style=flat)](https://npmjs.org/package/ts-node)
 [![NPM downloads](https://img.shields.io/npm/dm/ts-node.svg?style=flat)](https://npmjs.org/package/ts-node)