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

Josh-Cena · 2022-02-17T05:19:39Z

This PR:

Upgrades Docusaurus to beta.15 (includes some cool new features, not sure if they will be used in the future)
Makes the code files formatted (we have a pretty conservative prettierignore pattern, so I also constrained the range to those that absolutely need to be formatted)
Makes the metadata included on every page, not just the index page. (Pretty sure I saw cspotcode wondering if it's possible somewhere, but can't find the issue now. Anyways, it's certainly possible!)

Do you have any plans for cool documentation features? I'm here if you need help with Docusaurus APIs and we may even implement new ones for your convenience.

Josh-Cena · 2022-02-17T05:21:09Z

website/docusaurus.config.js

@@ -139,4 +153,38 @@ module.exports = {
      },
    ],
  ],
+  // Misleading API, probably will be refactored in Docusaurus, but this is
+  // simply a list of <link> tags


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>?

Josh-Cena · 2022-02-17T05:22:19Z

website/docusaurus.config.js

        },
+        blog: false,


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

cspotcode

Thanks, a couple questions for review:

Upgrades Docusaurus to beta.15 (includes some cool new features, not sure if they will be used in the future)

What new features do we get? Will the appearance of the website change, and should I do a visual review of the results?

Do you have any plans for cool documentation features? I'm here if you need help with Docusaurus APIs and we may even implement new ones for your convenience.

Unfortunately not, though I'm open to ideas. For me, the benefits of docusaurus are that I don't need to spend time building the website. I can focus on library and CLI features, and write docs as simple markdown, and docusaurus makes it look great. Docusaurus is a great fit, but it also means I'm not using any advanced features.

Having said that, I suppose I'm open to suggestions if you have ideas. I don't know about any of docusaurus's new features.

cspotcode · 2022-02-21T14:51:36Z

website/docusaurus.config.js

+        name: 'theme-color',
+        content: '#ffffff',
+      },
+    ],


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

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

cspotcode · 2022-02-21T14:52:00Z

website/docusaurus.config.js

+      rel: 'shortcut icon',
+      href: '/ts-node/img/favicon/favicon.ico',
+    },
+  ],


This looks new, what does it do?

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

cspotcode · 2022-02-21T14:52:33Z

website/package.json

-    "@docusaurus/theme-search-algolia": "^2.0.0-alpha.75",
+    "@docusaurus/core": "2.0.0-beta.15",
+    "@docusaurus/preset-classic": "2.0.0-beta.15",
+    "@docusaurus/theme-search-algolia": "2.0.0-beta.15",


I forgot we were on an alpha version, I guess alpha->beta is an improvement in stability.

The semantic difference between alpha and beta is not super big since we still ship breaking changes. The beta bump was mostly because we finally reached feature parity with v1 after the i18n release, so we are almost there for a stable release

Josh-Cena · 2022-02-21T15:09:36Z

Will the appearance of the website change, and should I do a visual review of the results?

Yes, you should preview the results locally since there are a few changes. For example, now the navbar items get an external link icon:

But thanks to the simplicity of the website, not much has changed beyond that.

What new features do we get?

The big one is category index pages, which means you can tuck the "General > Overview" page into the "General" category label itself instead of as a dropdown item, if you think that makes more sense.

For me, the benefits of docusaurus are that I don't need to spend time building the website. I can focus on library and CLI features

That's fair, and it's also what Docusaurus is built for :) I also think the ts-node website is good enough in its current form.

Josh-Cena · 2022-02-21T15:19:49Z

I think we can temporarily hold this off until later this week when we release beta.16, which would contain a few bug fixes that may affect some downstream website visitors.

cspotcode · 2022-02-21T15:22:50Z

The big one is category index pages, which means you can tuck the "General > Overview" page into the "General" category label itself instead of as a dropdown item, if you think that makes more sense.

Oh cool, that would also be nice for describing the "Recipes" section.

I'm getting this error when I run yarn start:

Error: error:0308010C:digital envelope routines::unsupported
    at String.replace (<anonymous>)
client (webpack 5.69.1) compiled with 1 error

It looks like I might be hitting facebook/docusaurus#5778? I'm running node 17.3.1. Is the fix to upgrade webpack? You may have already done this in the PR; I make a habit of defensively reverting any lockfile changes and instead allowing my local yarn to modify the lockfile, so that may have caused the error.

cspotcode · 2022-02-21T15:38:38Z

now the navbar items get an external link icon:

I see that docusaurus's own website is somehow able to suppress the external link icon, for example, for this link to github:

How is that possible? I see they're setting a className, but it looks like className does not suppress the <svg> so I'm not sure what's doing that.

Josh-Cena · 2022-02-21T15:39:01Z

It looks like I might be hitting facebook/docusaurus#5778? I'm running node 17.3.1. Is the fix to upgrade webpack? You may have already done this in the PR; I make a habit of defensively reverting any lockfile changes and instead allowing my local yarn to modify the lockfile, so that may have caused the error.

Yes, you need to upgrade Webpack. We have fixed it ourselves, and the lockfile update is needed :)

Josh-Cena · 2022-02-21T15:40:02Z

I see that docusaurus's own website is somehow able to suppress the external link icon, for example, for this link to github:

That's because we have set a custom ::after pseudoelement to show the GitHub icon. If you don't like the external link icons or want them styled differently, I can handle that for you.

cspotcode · 2022-02-21T15:45:28Z

If you don't like the external link icons or want them styled differently, I can handle that for you.

Thanks, yeah can we try seeing what it looks like without those icons?

Yes, you need to upgrade Webpack

I tried yarn upgrade webpack, confirmed that I have webpack 5.69.1, but the problem persists. Maybe there's something else I need to upgrade?

yarn why webpack

❯ yarn why webpack
yarn why v1.22.15
[1/4] Why do we have the module "webpack"...?
[2/4] Initialising dependency graph...
[3/4] Finding dependency...
[4/4] Calculating file sizes...
=> Found "[email protected]"
info Reasons this module exists
   - "@docusaurus#core" depends on it
   - Hoisted from "@docusaurus#core#webpack"
   - Hoisted from "@docusaurus#core#@docusaurus#mdx-loader#webpack"
   - Hoisted from "@docusaurus#preset-classic#@docusaurus#plugin-content-blog#webpack"
   - Hoisted from "@docusaurus#preset-classic#@docusaurus#plugin-content-docs#webpack"
   - Hoisted from "@docusaurus#preset-classic#@docusaurus#plugin-content-pages#webpack"
info Disk size without dependencies: "7.34MB"
info Disk size with unique dependencies: "7.34MB"
info Disk size with transitive dependencies: "7.34MB"
info Number of shared dependencies: 48
Done in 0.48s.

cspotcode · 2022-02-21T16:24:39Z

Nevermind, I got the upgrade to work by removing docusaurus, yarn to prune, and then re-adding it and running yarn to install. I guess something other than webpack in the dependency tree was causing the errors.

cspotcode · 2022-02-22T15:52:53Z

Any luck excluding those external link icons from the navbar? I couldn't figure out how to do it.

Josh-Cena · 2022-02-25T09:54:05Z

@cspotcode Going back to this, I noticed you don't have an appId for Algolia. Have you by any chance received an email from them asking you to migrate to the new DocSearch infra? We will require appId for the next beta release.

website/package.json

cspotcode · 2022-02-26T00:41:06Z

@cspotcode Going back to this, I noticed you don't have an appId for Algolia. Have you by any chance received an email from them asking you to migrate to the new DocSearch infra? We will require appId for the next beta release.

Found it:

Your new appId: BYGNLKSCOV
Your new apiKey: 74ac2b781b0cf603c2f1b5e4f44e1c69
Your indexName: ts-node

Josh-Cena · 2022-02-26T02:01:37Z

Upgraded to beta.16. With this release comes the doc breadcrumbs:

If you don't like it, we can turn it off as well. I also changed the Prism theme to a more accessible one in light mode.

cspotcode · 2022-02-26T02:34:34Z

Sounds good, the breadcrumbs are nice. Does "more accessible" mean it's colorblind-friendly?

Josh-Cena · 2022-02-26T02:38:06Z

No, just that it blends more nicely with the page... A dark code block on a light-themed page may not be accessible to visually challenged people who have to use a light background. It's also just more aesthetically appealing.

cspotcode · 2022-02-28T18:40:19Z

No, just that it blends more nicely with the page... A dark code block on a light-themed page may not be accessible to visually challenged people who have to use a light background. It's also just more aesthetically appealing.

Wow, now that you point this out, I can't believe I didn't notice it. This is a big improvement, thanks.

build-readme.mjs to strip twoslash prefixes, fix a couple typos and docs mistakes found due to the above (yay), pin yarn version

cspotcode · 2022-03-03T04:21:50Z

This is looking good. Since I ended up adding shiki and discovered bug shikijs/twoslash#141, and since you said beta.17 is right around the corner, I figure I'll hold off on merging till both of those are resolved.

codecov · 2022-03-03T04:25:49Z

Codecov Report

Merging #1645 (47dbfa4) into docs (abc616e) will increase coverage by 0.01%.
The diff coverage is n/a.

Impacted Files	Coverage Δ
src/ts-internals.ts	`45.20% <0.00%> (-2.74%)`	⬇️
src/esm.ts	`82.69% <0.00%> (-1.52%)`	⬇️
src/index.ts	`77.48% <0.00%> (-0.43%)`	⬇️
src/resolver-functions.ts	`86.00% <0.00%> (+1.55%)`	⬆️
dist-raw/node-esm-default-get-format.js	`80.00% <0.00%> (+5.71%)`	⬆️
dist-raw/node-errors.js	`100.00% <0.00%> (+50.00%)`	⬆️

Josh-Cena · 2022-03-03T05:13:44Z

This PR is getting busy... 😄

cspotcode · 2022-03-03T18:16:56Z

/me slaps roof of PR

Josh-Cena · 2022-03-04T05:55:30Z

Bumped to beta.17. The color mode toggle is changed:

Again, it's customizable, depending on what you like

… and it also adds erroneous links to ts-node sub-config

See: - facebook/docusaurus#5778 - TypeStrong/ts-node#1645

* build(docs): update package-lock to v2 The new package-lock version contains more details and is more explicit. Before updating packages with npm it makes sense to update this. * deps(docs): bump docusaurus to 2.0.1 * fix(docs): move hideableSidebar config This fixes the following error at startup: > [ERROR] ValidationError: themeConfig.hideableSidebar has been moved to > themeConfig.docs.sidebar.hideable. * fix(docs): use new algolia appId This was a new requirement from DocSearch. See https://docusaurus.io/blog/2021/11/21/algolia-docsearch-migration for more details. * fix(docs): align new css urls It seems the urls are resolved differently now. The previous urls caused compilation errors during `npm start`. Removing the `feel-scala` prefix fixed these errors. * ci(docs): update to node v18 * deps(docs): update to fix webpack See: - facebook/docusaurus#5778 - TypeStrong/ts-node#1645

See: - facebook/docusaurus#5778 - TypeStrong/ts-node#1645

* build(docs): update package-lock to v2 The new package-lock version contains more details and is more explicit. Before updating packages with npm it makes sense to update this. * deps(docs): bump docusaurus to 2.0.1 * deps(docs): update to fix webpack See: - facebook/docusaurus#5778 - TypeStrong/ts-node#1645 * deps(docs): install axios for http requests With almost 100k GH stars, this is one of the most commonly used HTTP libraries for nodejs. * deps(docs): install use-editable This library allows us to build an editable React component. * feat(docs): add tutorial-test page Adds a test page (MDX) called `tutorial-test.mdx` to develop the LiveFeel and Editor components. * docs: add tutorial test page to sidebar * make it easy to play around with the new editor Co-authored-by: Philipp Ossler <[email protected]>

chore(website): upgrade Docusaurus, format files

0395a19

Josh-Cena commented Feb 17, 2022

View reviewed changes

cspotcode reviewed Feb 21, 2022

View reviewed changes

remove external link icon

e34a3b0

Josh-Cena commented Feb 25, 2022

View reviewed changes

website/package.json Show resolved Hide resolved

upgrade Docusaurus to beta.16

bfa3e69

fix lock

f8e052d

cspotcode added this to the 10.7.0 milestone Mar 3, 2022

cspotcode changed the base branch from main to docs March 3, 2022 00:36

cspotcode added 2 commits March 2, 2022 23:07

add shiki-twoslash, pick code highlighting themes, update

b34fa81

build-readme.mjs to strip twoslash prefixes, fix a couple typos and docs mistakes found due to the above (yay), pin yarn version

linting

6080b7e

cspotcode removed this from the 10.7.0 milestone Mar 3, 2022

cspotcode added this to the 10.8.0 milestone Mar 3, 2022

Josh-Cena and others added 4 commits March 4, 2022 13:57

beta.17

cf87758

point breadcrumb home to /docs

135ec4b

fix prettier config

b4a7129

remove twoslash tsconfig renderer due to rendering bug on dark theme,…

47dbfa4

… and it also adds erroneous links to ts-node sub-config

cspotcode modified the milestones: 10.8.0, 10.7.0 Mar 4, 2022

cspotcode changed the title ~~chore(website): upgrade Docusaurus, format files~~ chore(website): upgrade Docusaurus, format files, add shiki-twoslash Mar 4, 2022

cspotcode merged commit 661154a into TypeStrong:docs Mar 4, 2022

Josh-Cena deleted the site-upgrade branch March 4, 2022 07:13

cspotcode mentioned this pull request Mar 4, 2022

Add shiki-twoslash tooltips to docsite #1670

Closed

cspotcode linked an issue Mar 4, 2022 that may be closed by this pull request

Add shiki-twoslash tooltips to docsite #1670

Closed

korthout added a commit to camunda/feel-scala that referenced this pull request Aug 10, 2022

deps(docs): update to fix webpack

6d08597

See: - facebook/docusaurus#5778 - TypeStrong/ts-node#1645

korthout added a commit to camunda/feel-scala that referenced this pull request Aug 10, 2022

deps(docs): update to fix webpack

a41a266

See: - facebook/docusaurus#5778 - TypeStrong/ts-node#1645

upgradingdave pushed a commit to camunda/feel-scala that referenced this pull request Aug 11, 2022

deps(docs): update to fix webpack

6c8dc46

See: - facebook/docusaurus#5778 - TypeStrong/ts-node#1645

saig0 pushed a commit to camunda/feel-scala that referenced this pull request Aug 11, 2022

deps(docs): update to fix webpack

6fc0421

See: - facebook/docusaurus#5778 - TypeStrong/ts-node#1645

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

Josh-Cena commented Feb 17, 2022

Josh-Cena Feb 17, 2022

Josh-Cena Feb 17, 2022

cspotcode left a comment

cspotcode Feb 21, 2022

Josh-Cena Feb 21, 2022

cspotcode Feb 21, 2022

Josh-Cena Feb 21, 2022

cspotcode Feb 21, 2022

Josh-Cena Feb 21, 2022

Josh-Cena commented Feb 21, 2022 •

edited

Loading

Josh-Cena commented Feb 21, 2022 •

edited

Loading

cspotcode commented Feb 21, 2022

cspotcode commented Feb 21, 2022 •

edited

Loading

Josh-Cena commented Feb 21, 2022

Josh-Cena commented Feb 21, 2022

cspotcode commented Feb 21, 2022

cspotcode commented Feb 21, 2022

cspotcode commented Feb 22, 2022

Josh-Cena commented Feb 25, 2022

cspotcode commented Feb 26, 2022

Josh-Cena commented Feb 26, 2022

cspotcode commented Feb 26, 2022

Josh-Cena commented Feb 26, 2022 •

edited

Loading

cspotcode commented Feb 28, 2022

cspotcode commented Mar 3, 2022

codecov bot commented Mar 3, 2022 •

edited

Loading

Josh-Cena commented Mar 3, 2022

cspotcode commented Mar 3, 2022

Josh-Cena commented Mar 4, 2022

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

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

Conversation

Josh-Cena commented Feb 17, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cspotcode left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Josh-Cena commented Feb 21, 2022 • edited Loading

Josh-Cena commented Feb 21, 2022 • edited Loading

cspotcode commented Feb 21, 2022

cspotcode commented Feb 21, 2022 • edited Loading

Josh-Cena commented Feb 21, 2022

Josh-Cena commented Feb 21, 2022

cspotcode commented Feb 21, 2022

cspotcode commented Feb 21, 2022

cspotcode commented Feb 22, 2022

Josh-Cena commented Feb 25, 2022

cspotcode commented Feb 26, 2022

Josh-Cena commented Feb 26, 2022

cspotcode commented Feb 26, 2022

Josh-Cena commented Feb 26, 2022 • edited Loading

cspotcode commented Feb 28, 2022

cspotcode commented Mar 3, 2022

codecov bot commented Mar 3, 2022 • edited Loading

Codecov Report

Josh-Cena commented Mar 3, 2022

cspotcode commented Mar 3, 2022

Josh-Cena commented Mar 4, 2022

Josh-Cena commented Feb 21, 2022 •

edited

Loading

Josh-Cena commented Feb 21, 2022 •

edited

Loading

cspotcode commented Feb 21, 2022 •

edited

Loading

Josh-Cena commented Feb 26, 2022 •

edited

Loading

codecov bot commented Mar 3, 2022 •

edited

Loading