Skip to content

chore(website): upgrade Docusaurus, format files, add shiki-twoslash#1645

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cspotcode merged 10 commits into from
Mar 4, 2022
Merged

chore(website): upgrade Docusaurus, format files, add shiki-twoslash #1645

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
0395a19
chore(website): upgrade Docusaurus, format files
Josh-Cena Feb 17, 2022
e34a3b0
remove external link icon
Josh-Cena Feb 25, 2022
bfa3e69
upgrade Docusaurus to beta.16
Josh-Cena Feb 26, 2022
f8e052d
fix lock
Josh-Cena Feb 26, 2022
b34fa81
add shiki-twoslash, pick code highlighting themes, update
cspotcode Mar 3, 2022
6080b7e
linting
cspotcode Mar 3, 2022
cf87758
beta.17
Josh-Cena Mar 4, 2022
135ec4b
point breadcrumb home to /docs
Josh-Cena Mar 4, 2022
b4a7129
fix prettier config
cspotcode Mar 4, 2022
47dbfa4
remove twoslash tsconfig renderer due to rendering bug on dark theme,…
cspotcode Mar 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .prettierignore
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
2 changes: 1 addition & 1 deletion website/docs/module-type-overrides.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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,
Expand Down
4 changes: 2 additions & 2 deletions website/docs/recipes/ava.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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": [
Expand All@@ -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": {
Expand Down
5 changes: 4 additions & 1 deletion website/docs/troubleshooting.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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;
```

Expand Down
12 changes: 7 additions & 5 deletions website/docs/types.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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": ".",
Expand All@@ -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`.
6 changes: 3 additions & 3 deletions website/docs/usage.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -29,23 +29,23 @@ ts-node-cwd 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
```
Expand Down
99 changes: 76 additions & 23 deletions website/docusaurus.config.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -19,7 +19,7 @@ module.exports = {
// //isCloseable: false, // Defaults to `true`.
// },
colorMode: {
respectPrefersColorScheme: true
respectPrefersColorScheme: true,
},
navbar: {
title: 'ts-node',
Expand DownExpand Up@@ -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',
},
],

@cspotcodecspotcodeFeb 21, 2022

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks new, what does it do? Do we need to make these colors match something else in our config?

@Josh-CenaJosh-CenaFeb 21, 2022

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a replacement for the <Head> tags you had in index.js before.

// footer: {
// style: 'dark',
// links: [
Expand DownExpand Up@@ -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: [
Expand All@@ -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,

@Josh-CenaJosh-CenaFeb 17, 2022

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

blog: undefined would still initialize the blog plugin, which would create some default routes like /blog/archive, even if there aren't any posts.

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

@Josh-CenaJosh-CenaFeb 17, 2022

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's more like a note to myself. I have this comment on multiple websites I helped set up now, but I still can't think of a better API. We'll probably have an htmlTags API that allows you to inject arbitrary HTML tags, not just <link>?

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',
},
],

@cspotcodecspotcodeFeb 21, 2022

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks new, what does it do?

@Josh-CenaJosh-CenaFeb 21, 2022

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above, just a replacement for the head tags so they show up on every page.

};
17 changes: 11 additions & 6 deletions website/package.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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",
Comment thread
cspotcode marked this conversation as resolved.
"@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",
Expand All@@ -42,5 +42,10 @@
"last 1 firefox version",
"last 1 safari version"
]
},
"packageManager": "yarn@1.22.17",
"volta": {
"extends": "../package.json",
"yarn": "1.22.17"
}
}
Loading