Merge docs into main for 10.7.0

* chore(website): upgrade Docusaurus, format files

* remove external link icon

* upgrade Docusaurus to beta.16

* fix lock

* add shiki-twoslash, pick code highlighting themes, update
build-readme.mjs to strip twoslash prefixes, fix a couple typos
and docs mistakes found due to the above (yay), pin yarn version

* linting

* beta.17

* point breadcrumb home to /docs

* fix prettier config

* remove twoslash tsconfig renderer due to rendering bug on dark theme, and it also adds erroneous links to ts-node sub-config

Co-authored-by: Andrew Bradley <[email protected]>

Co-authored-by: Joshua Chen <[email protected]>

Author: cspotcode

.prettierignore

@@ -6,6 +6,11 @@
 !/scripts
 !/src
 !/tests
+!/website
+/website/.docusaurus
+/website/docs
+/website/readme-sources
+/website/static
 tests/main-realpath/symlink/tsconfig.json
 tests/throw error.ts
 tests/throw error react tsx.tsx

website/docs/module-type-overrides.md

@@ -17,7 +17,7 @@ CommonJS or ESM.  Node supports similar overriding via `.cjs` and `.mjs` file ex
 
 The following example tells ts-node to execute a webpack config as CommonJS:
 
-```json title=tsconfig.json
+```json title="tsconfig.json"
 {
   "ts-node": {
     "transpileOnly": true,

website/docs/recipes/ava.md

@@ -8,7 +8,7 @@ Assuming you are configuring AVA via your `package.json`, add one of the followi
 
 Use this configuration if your `package.json` does not have `"type": "module"`.
 
-```json title"package.json"
+```json title="package.json"
 {
   "ava": {
     "extensions": [
@@ -25,7 +25,7 @@ Use this configuration if your `package.json` does not have `"type": "module"`.
 
 This configuration is necessary if your `package.json` has `"type": "module"`.
 
-```json title"package.json"
+```json title="package.json"
 {
   "ava": {
     "extensions": {

website/docs/troubleshooting.md

@@ -71,7 +71,10 @@ the [tsconfig `"target"` option](https://www.typescriptlang.org/tsconfig#target)
 
 For example, `node` 12 does not understand the `?.` optional chaining operator.  If you use `"target": "esnext"`, then the following TypeScript syntax:
 
-```typescript
+```typescript twoslash
+export {};
+var foo: {bar: string} | undefined;
+// ---cut---
 const bar: string | undefined = foo?.bar;
 ```
 

website/docs/types.md

@@ -28,15 +28,15 @@ Example project structure:
 
 Example module declaration file:
 
-```typescript
+```typescript twoslash
 declare module '<module_name>' {
     // module definitions go here
 }
 ```
 
 For module definitions, you can use [`paths`](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping):
 
-```json
+```json title="tsconfig.json"
 {
   "compilerOptions": {
     "baseUrl": ".",
@@ -49,9 +49,11 @@ For module definitions, you can use [`paths`](https://www.typescriptlang.org/doc
 
 An alternative approach for definitions of third-party libraries are [triple-slash directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html). This may be helpful if you prefer not to change your TypeScript `compilerOptions` or structure your custom type definitions when using `typeRoots`. Below is an example of the triple-slash directive as a relative path within your project:
 
-```typescript
-/// <reference types="./types/untyped_js_lib" />
-import UntypedJsLib from "untyped_js_lib"
+```typescript twoslash
+/// <reference path="./types/untyped_js_lib" />
+import {Greeter} from "untyped_js_lib"
+const g = new Greeter();
+g.sayHello();
 ```
 
 **Tip:** If you _must_ use `files`, `include`, or `exclude`, enable `--files` flags or set `TS_NODE_FILES=true`.

website/docs/usage.md

@@ -32,23 +32,23 @@ ts-node-esm script.ts
 
 ## Shebang
 
-```typescript
+```typescript twoslash
 #!/usr/bin/env ts-node
 
 console.log("Hello, world!")
 ```
 
 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
+```typescript twoslash
 #!/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
 ```
 
 To write scripts with maximum portability, [specify all options in your `tsconfig.json`](./configuration#via-tsconfigjson-recommended) and omit them from the shebang.
 
-```typescript
+```typescript twoslash
 #!/usr/bin/env ts-node
 // This shebang works everywhere
 ```

website/docusaurus.config.js

@@ -19,7 +19,7 @@ module.exports = {
     //   //isCloseable: false, // Defaults to `true`.
     // },
     colorMode: {
-      respectPrefersColorScheme: true
+      respectPrefersColorScheme: true,
     },
     navbar: {
       title: 'ts-node',
@@ -61,6 +61,20 @@ module.exports = {
         },
       ],
     },
+    metadata: [
+      {
+        name: 'msapplication-TileColor',
+        content: '#2b5797',
+      },
+      {
+        name: 'msapplication-config',
+        content: '/ts-node/img/favicon/browserconfig.xml',
+      },
+      {
+        name: 'theme-color',
+        content: '#ffffff',
+      },
+    ],
     // footer: {
     //   style: 'dark',
     //   links: [
@@ -99,23 +113,14 @@ module.exports = {
     //   // copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
     // },
     prism: {
-      // for syntax highlighting
-      // additionalLanguages: ['powershell'],
+      // Note: these themes are ignored due to using shiki-twoslash
+      theme: require('prism-react-renderer/themes/vsLight'),
+      darkTheme: require('prism-react-renderer/themes/vsDark'),
     },
     algolia: {
-      apiKey: 'c882a0a136ef4e15aa99db604280caa6',
+      appId: 'BYGNLKSCOV',
+      apiKey: '74ac2b781b0cf603c2f1b5e4f44e1c69',
       indexName: 'ts-node',
-
-      // Optional: see doc section below
-      // contextualSearch: true,
-
-      // Optional: see doc section below
-      // appId: 'YOUR_APP_ID',
-
-      // Optional: Algolia search parameters
-      // searchParameters: {},
-
-      //... other Algolia params
     },
   },
   presets: [
@@ -124,19 +129,67 @@ module.exports = {
       {
         docs: {
           sidebarPath: require.resolve('./sidebars.js'),
-          editUrl:
-            'https://github.com/TypeStrong/ts-node/edit/docs/website/',
+          editUrl: 'https://github.com/TypeStrong/ts-node/edit/docs/website/',
         },
-        // blog: {
-        //   showReadingTime: true,
-        //   // Please change this to your repo.
-        //   editUrl:
-        //     'https://github.com/facebook/docusaurus/edit/master/website/blog/',
-        // },
+        blog: false,
         theme: {
           customCss: require.resolve('./src/css/custom.css'),
         },
       },
     ],
+    [
+      'docusaurus-preset-shiki-twoslash',
+      {
+        // https://github.com/shikijs/twoslash/blob/main/packages/shiki-twoslash/README.md#user-settings
+
+        // langs: ["shell", "typescript", "javascript", "ts", "js", "tsx", "jsx", "json", "jsonc"],
+        includeJSDocInHover: true,
+
+        themes: ['github-light', 'nord'],
+
+        // VSCode default
+        // themes: ["light-plus", "dark-plus"],
+
+        // Other options
+        // themes: ["min-light", "nord"],
+        // themes: ["min-light", "min-dark"],
+        // themes: ["github-light", "github-dark"],
+        // themes: ["solarized-light", "solarized-dark"],
+      },
+    ],
+  ],
+  // Misleading API that probably will be refactored in Docusaurus, but this is
+  // simply a list of <link> tags
+  stylesheets: [
+    {
+      rel: 'apple-touch-icon',
+      sizes: '180x180',
+      href: '/ts-node/img/favicon/apple-touch-icon.png',
+    },
+    {
+      rel: 'icon',
+      type: 'image/png',
+      sizes: '32x32',
+      href: '/ts-node/img/favicon/favicon-32x32.png',
+    },
+    {
+      rel: 'icon',
+      type: 'image/png',
+      sizes: '16x16',
+      href: '/ts-node/img/favicon/favicon-16x16.png',
+    },
+    {
+      rel: 'manifest',
+      href: '/ts-node/img/favicon/site.webmanifest',
+    },
+    {
+      rel: 'mask-icon',
+      href: '/ts-node/img/favicon/safari-pinned-tab.svg',
+      color: '#5bbad5',
+    },
+    {
+      rel: 'shortcut icon',
+      href: '/ts-node/img/favicon/favicon.ico',
+    },
   ],
 };

website/package.json

@@ -13,15 +13,15 @@
     "build-readme": "./scripts/build-readme.mjs"
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-alpha.75",
-    "@docusaurus/preset-classic": "2.0.0-alpha.75",
-    "@docusaurus/theme-search-algolia": "^2.0.0-alpha.75",
-    "@mdx-js/react": "^1.6.21",
+    "@docusaurus/core": "2.0.0-beta.17",
+    "@docusaurus/preset-classic": "2.0.0-beta.17",
+    "@mdx-js/react": "^1.6.22",
     "@types/js-yaml": "^4.0.0",
     "clsx": "^1.1.1",
+    "docusaurus-preset-shiki-twoslash": "^1.1.36",
     "js-yaml": "^4.0.0",
-    "react": "^16.8.4",
-    "react-dom": "^16.8.4",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
     "remark": "^13.0.0",
     "remark-behead": "^2.3.3",
     "remark-frontmatter": "^3.0.0",
@@ -42,5 +42,10 @@
       "last 1 firefox version",
       "last 1 safari version"
     ]
+  },
+  "packageManager": "[email protected]",
+  "volta": {
+    "extends": "../package.json",
+    "yarn": "1.22.17"
   }
 }