Rewrite all guides

* add twoslash
* add mentions of micromark
* modernize jsdoc, jsx use
* rewrite out of date “Create an editor”, using esbuild and react
* change plugins highlighted in “Intro to unified”
* rewrite “Narrow node TypeScript”, with new `Nodes` unions

Author: wooorm

.remarkrc.js

@@ -25,7 +25,7 @@ const naturalLanguage = unified().use([
   retextEnglish,
   retextPresetWooorm,
   [retextEquality, {ignore: ['whitespace']}],
-  retextPassive,
+  [retextPassive, {ignore: ['hidden']}],
   [retextProfanities, {sureness: 1}],
   [retextReadability, {age: 18, minWords: 8}],
   [retextSimplify, {ignore: ['function', 'interface', 'maintain', 'type']}],

asset/browser.js

@@ -0,0 +1,66 @@
+/// <reference lib="dom" />
+
+/* eslint-env browser */
+
+import {computePosition, shift} from '@floating-ui/dom'
+
+if ('paintWorklet' in CSS) {
+  // @ts-expect-error: CSS is not yet fully typed.
+  CSS.paintWorklet.addModule('https://esm.sh/css-houdini-squircle@0.3?bundle')
+}
+
+const popoverTargets = /** @type {Array<HTMLElement>} */ (
+  Array.from(document.querySelectorAll('.rehype-twoslash-popover-target'))
+)
+
+for (const popoverTarget of popoverTargets) {
+  /** @type {NodeJS.Timeout | number} */
+  let timeout = 0
+
+  popoverTarget.addEventListener('click', function () {
+    popoverShow(popoverTarget)
+  })
+
+  popoverTarget.addEventListener('mouseenter', function () {
+    clearTimeout(timeout)
+    timeout = setTimeout(function () {
+      popoverShow(popoverTarget)
+    }, 300)
+  })
+
+  popoverTarget.addEventListener('mouseleave', function () {
+    clearTimeout(timeout)
+  })
+
+  if (popoverTarget.classList.contains('rehype-twoslash-autoshow')) {
+    popoverShow(popoverTarget)
+  }
+}
+
+/**
+ * @param {HTMLElement} popoverTarget
+ *   Popover target.
+ * @returns {undefined}
+ *   Nothing.
+ */
+function popoverShow(popoverTarget) {
+  const id = popoverTarget.dataset.popoverTarget
+  if (!id) return
+  const popover = document.getElementById(id)
+  if (!popover) return
+
+  popover.showPopover()
+
+  computePosition(popoverTarget, popover, {
+    placement: 'bottom',
+    middleware: [shift({padding: 5})]
+  }).then(
+    /**
+     * @param {{x: number, y: number}} value
+     */
+    function (value) {
+      popover.style.left = value.x + 'px'
+      popover.style.top = value.y + 'px'
+    }
+  )
+}

asset/dark.css

@@ -163,6 +163,19 @@ a.tag:focus .count {
   border-bottom-color: var(--gray-6);
 }
 
+.highlight:is(:hover, :focus-within) .rehype-twoslash-popover-target {
+  background-color: var(--gray-5);
+}
+
+.rehype-twoslash-popover {
+  background-color: var(--gray-9);
+  border-color: var(--gray-7);
+}
+
+.rehype-twoslash-popover-description {
+  background-color: var(--gray-9);
+}
+
 .screen {
   background-image: linear-gradient(150deg, #0366d6 15%, #24292e 85%);
 }

asset/houdini.js

@@ -249,10 +249,13 @@ abbr {
 }
 
 .mdast .hl,
+.micromark .hl,
 .remark .hl,
 .content .mdast:hover .hl,
+.content .micromark:hover .hl,
 .content .remark:hover .hl,
 .content .mdast:focus .hl,
+.content .micromark:focus .hl,
 .content .remark:focus .hl {
   color: hsl(0deg 97% 43%);
 }
@@ -827,6 +830,56 @@ a.tag:focus .count {
   border-bottom-color: var(--gray-3);
 }
 
+.rehype-twoslash-completion-deprecated {
+  opacity: 0.5;
+}
+
+.rehype-twoslash-popover-target {
+  cursor: default;
+}
+
+.highlight:is(:hover, :focus-within) .rehype-twoslash-popover-target {
+  background-color: var(--gray-2);
+}
+
+/* Wavy underline for errors. */
+.rehype-twoslash-error-target {
+  background-repeat: repeat-x;
+  background-position: bottom left;
+  background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 6 3" enable-background="new 0 0 6 3" height="3" width="6"><g fill="%23c94824"><polygon points="5.5,0 2.5,3 1.1,3 4.1,0"/><polygon points="4,0 6,2 6,0.6 5.4,0"/><polygon points="0,2 1,3 2.4,3 0,0.6"/></g></svg>');
+}
+
+/* The content that will be shown in the tooltip. */
+.rehype-twoslash-popover {
+  position: absolute;
+  max-width: calc(45 * (1em + 1ex));
+  padding: calc(0.5 * (1em + 1ex));
+  margin: 0;
+  background-color: var(--gray-0);
+  border: 1px solid var(--gray-2);
+  border-radius: 3px;
+}
+
+/* No padding if we have a padded code block (and perhaps more blocks) */
+.rehype-twoslash-popover:has(.rehype-twoslash-popover-code) {
+  padding: 0;
+}
+
+.rehype-twoslash-popover-code {
+  /* Overwrite `.content pre` */
+  margin: 0 !important;
+}
+
+.rehype-twoslash-popover-code > code {
+  mask-image: none;
+  border-radius: 0;
+}
+
+.rehype-twoslash-popover-description {
+  background-color: var(--gray-0);
+  padding: 0 calc(2 * (1em + 1ex));
+}
+
 @media (width <= 48em) {
   .x-show-l {
     display: none;

asset/image/unified-overview.png

@@ -1,9 +1,11 @@
 // Jargon
 API
+CLI
+XSS
 attacher
 bundler
-CLI
 debounced
+esbuild
 hacky
 linter
 math
@@ -20,31 +22,33 @@ stdout
 stringifier
 stringify
 syntaxes
-XSS
+whitespace
 
 // Names, products, etc.
 BundlePhobia
-browserify
+CDN
 CommonMark
 DOM
+Deno
 GFM
 HSL
-hast
 JSDoc
 JSON
 JSX
-MacBook
 MDX
-mdast
+MacBook
 Node.js
+Otander
+Preact
+hast
+mdast
 nlcst
 npm
-Otander
 rehype
 remark
 retext
-unist
 unified
+unist
 vfile
 xast
 xo

asset/index.css

@@ -1,17 +1,19 @@
 ---
+authorGithub: ChristianMurphy
+author: Christian Murphy
+description: How to build content with syntax trees
 group: recipe
 index: 8
-title: Build a syntax tree
-description: How to build content with syntax trees
+modified: 2024-08-02
+published: 2020-06-09
 tags:
-  - unist
-  - mdast
+  - esast
   - hast
+  - mdast
+  - nlcst
+  - unist
   - xast
-author: Christian Murphy
-authorGithub: ChristianMurphy
-published: 2020-06-09
-modified: 2020-06-15
+title: Build a syntax tree
 ---
 
 ## How to build a syntax tree
@@ -28,10 +30,11 @@ The most basic way to create a tree is with plain object and arrays.
 To prevent type errors, this can be checked with the types for the given syntax
 tree language, in this case mdast:
 
-```ts
+```ts twoslash
 import type {Root} from 'mdast'
 
-// Note the `: Root` is a TypeScript annotation. Remove it (and the import) for plain JavaScript.
+// Note the `: Root` is a TypeScript annotation.
+// For plain JavaScript, remove it (and the import).
 const mdast: Root = {
   type: 'root',
   children: [
@@ -54,9 +57,14 @@ It’s also possible to build trees with [`unist-builder`][u].
 It allows a more concise, “hyperscript” like syntax (which is also like
 `React.createElement`):
 
-```js
+```js twoslash
+/**
+ * @import {Root} from 'mdast'
+ */
+
 import {u} from 'unist-builder'
 
+/** @type {Root} */
 const mdast = u('root', [
   u('paragraph', [
     u('text', 'example')
@@ -68,7 +76,9 @@ const mdast = u('root', [
 
 When working with hast (HTML), [`hastscript`][h] can be used.
 
-```js
+```js twoslash
+/// <reference types="node" />
+// ---cut---
 import {h, s} from 'hastscript'
 
 console.log(
@@ -81,7 +91,7 @@ console.log(
 
 // SVG:
 console.log(
-  s('svg', {viewbox: '0 0 500 500', xmlns: 'http://www.w3.org/2000/svg'}, [
+  s('svg', {viewBox: '0 0 500 500', xmlns: 'http://www.w3.org/2000/svg'}, [
     s('title', 'SVG `<circle>` element'),
     s('circle', {cx: 120, cy: 120, r: 100})
   ])
@@ -90,9 +100,10 @@ console.log(
 
 `hastscript` can also be used as a JSX configuration comment:
 
-```jsx
-/** @jsx h @jsxFrag null */
-import {h} from 'hastscript'
+```tsx twoslash
+/// <reference types="node" />
+// ---cut---
+/** @jsxImportSource hastscript */
 
 console.log(
   <form method="POST">
@@ -108,7 +119,9 @@ console.log(
 When working with xast (XML), [`xastscript`][x]
 can be used.
 
-```js
+```js twoslash
+/// <reference types="node" />
+// ---cut---
 import {x} from 'xastscript'
 
 console.log(
@@ -122,9 +135,10 @@ console.log(
 
 `xastscript` can also be used as a JSX configuration comment:
 
-```jsx
-/** @jsx x @jsxFrag null */
-import {x} from 'xastscript'
+```tsx twoslash
+/// <reference types="node" />
+// ---cut---
+/** @jsxImportSource xastscript */
 
 console.log(
   <album id={123}>