chore: upgrade to docusaurus 3

- quote jsx text that contained `{}` since it was parsed as expression - replace mdx html comments with `{/**/}` since they are not supported - upgrade to react 18
wixplosives · Nov 22, 2023 · 8dfa636 · 8dfa636
1 parent 214636a
commit 8dfa636
Show file tree

Hide file tree

Showing 12 changed files with 4,983 additions and 2,553 deletions.
diff --git a/docs/getting-started/manual-integration.mdx b/docs/getting-started/manual-integration.mdx
@@ -23,7 +23,7 @@ Stylable officially supports two different bundlers, [webpack](./webpack-integra
 
 To integrate Stylable with server-side rendering, you have two options.
 
-- The first option is to pre-build your stylesheets and assets using the Stylable, and then consume them on the server without any further Stylable-specific integration. <!-- TODO: Add instructions in the ssr guide for pre-building Stylable and add a link -->
+- The first option is to pre-build your stylesheets and assets using the Stylable, and then consume them on the server without any further Stylable-specific integration. {/* TODO: Add instructions in the ssr guide for pre-building Stylable and add a link */}
 - The second option is to use the [**Stylable** node integration](../guides/server-side-rendering.md#transforming-stylable-in-the-server), which allows you to load and render Stylable stylesheets directly on the server. To use this option, you will need to integrate `@stylable/node` into your server-side rendering pipeline.
 
 ## Component library

diff --git a/docs/getting-started/stylable-config.mdx b/docs/getting-started/stylable-config.mdx
@@ -54,7 +54,7 @@ The `stcConfig` export field is used as a single point to define multiple build
 
 To run this configuration, either run the CLI using the `stc` command, or pass the `stcConfig` option to the Webpack or rollup integrations.
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 
 <Tabs groupId="stcConfigExamples">
   <TabItem value="singleProject" label="Single build task" default>
@@ -133,11 +133,11 @@ type ProjectEntryValue<PRESET extends string> =
 
 </details>
 
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 To learn more about the various CLI flags, see the [CLI page](./tooling/cli#cli-arguments).
 
-<!-- todo: options diff in stcConfig to cli options -->
+{/* todo: options diff in stcConfig to cli options */}
 
 ## `webpackPlugin`
 

diff --git a/docs/getting-started/tooling/cli.mdx b/docs/getting-started/tooling/cli.mdx
@@ -15,7 +15,7 @@ It lets you:
 
 ## Installation
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 
 <Tabs groupId="packageManager">
   <TabItem value="npm" label="NPM" default>
@@ -34,7 +34,7 @@ yarn add @stylable/cli -D
   </TabItem>
 </Tabs>
 
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 ## Using the CLI
 

diff --git a/docs/guides/handbook/class.mdx b/docs/guides/handbook/class.mdx
@@ -55,14 +55,14 @@ The example above assumes that Stylable was run as part of a build process, usin
 
 Due to the fact that these class symbols are generated from the stylesheet, but are also consumed in JavaScript, we recommend using camelCase for class names to avoid cases that require [property accessors](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Property_accessors).
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 
 ```js
 import { classes } from "./dialog.st.css";
 
 classes.okButton;     // recommended
 classes["ok-button"]; // not recommended
 ```
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 We would further recommend to avoid using special characters that are not valid JavaScript identifiers.
diff --git a/docs/guides/handbook/extend.mdx b/docs/guides/handbook/extend.mdx
@@ -12,7 +12,7 @@ In this chapter, we'll see how to extend a stylesheet to target inner parts and
 
 **Current status:**
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 ```css title="player.st.css"
 .root {
   -st-states: registered,
@@ -35,7 +35,7 @@ Player .username {
   text-transform: uppercase;
 }
 ```
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 Previously, we manually customized the `Player` component by creating a selector that includes a [descendant combinator](https://developer.mozilla.org/en-US/docs/Web/CSS/Descendant_combinator) between the `Player` and our targeted parts. This selector is based on knowledge we have about the `Player` component structure, but this structure might change in the future, and break our assumptions.
 
@@ -45,7 +45,7 @@ To help us abstract our selector, we'll extend the `Player` stylesheet to gain a
 
 We'll first set the `-st-extends` property with the value of the imported `Player` stylesheet on the local `player` class.
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 ```css title="game.st.css"
 @st-import Player from "./player.st.css";
 
@@ -66,7 +66,7 @@ We'll first set the `-st-extends` property with the value of the imported `Playe
   </CodeBlock>
 </details>
 
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 We [previously saw](./import.mdx#stylesheet-root-selector) that we can't simply target an imported stylesheet, as that would affect all instances of it.
 
@@ -91,7 +91,7 @@ const Game = ({ className }) => (
 
 We can now use the custom pseudo-element syntax to safely target the `avatar` and `username` parts of the `Player` component.
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 ```css title="game.st.css"
 @st-import Player from "./player.st.css";
 
@@ -123,13 +123,13 @@ We can now use the custom pseudo-element syntax to safely target the `avatar` an
   </CodeBlock>
 </details>
 
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 ### Access a state
 
 Similar to how we used custom pseudo-elements to access inner parts of a component externally, we can now target custom pseudo-classes (states) of our extended parts as well.
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 ```css title="game.st.css"
 @st-import Player from "./player.st.css";
 
@@ -141,15 +141,15 @@ Similar to how we used custom pseudo-elements to access inner parts of a compone
 }
 /* ... */
 ```
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 ## Extend multiple levels
 
 Let's say that we want to turn our current `avatar` part, into a component to support a more complex design with separate elements for the `frame` and the `image`.
 
 To do this, we'll create a new `avatar.st.css` stylesheet, import it to `player.st.css`, and extend our `avatar` class with it.
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 ```css title="avatar.st.css"
 .root {}
 .frame {}
@@ -188,7 +188,7 @@ By extending a stylesheet, which in turn has a part that extends a stylesheet, w
   background: gold;
 }
 ```
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 :::tip Catch breaking changes
 Let's imagine a case, where the `Avatar` component has undergone refactoring which changed the part name `frame` to `box`. If we were using native CSS, and were aware of this change, we could try and manually locate all instances of `frame` and replace them with `box`. But if we were to miss an instance, CSS would provide no indication of the problem.

diff --git a/docs/guides/handbook/import.mdx b/docs/guides/handbook/import.mdx
@@ -7,13 +7,13 @@ import CodeBlock from '@theme/CodeBlock';
 
 In the [Runtime chapter](./runtime.md), we saw how a Stylable stylesheet's API can be imported into a JavaScript module, and how that API can be used. In this chapter, we'll see how our game example can be divided into linked stylesheet modules to provide a better development experience.
 
-<!-- - here we'll focus on importing symbols across stylesheets, and how to import stuff from javascript to Stylable stylesheets -->
+{/* - here we'll focus on importing symbols across stylesheets, and how to import stuff from javascript to Stylable stylesheets */}
 
 Up to this point, we've talked mostly about a single stylesheet for our project (`game.st.css`). Now we'll explore how to organize our code across multiple stylesheets.
 
 **Current status:**
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 ```css title="game.st.css"
 .board { /* ... */ }
 
@@ -23,13 +23,13 @@ Up to this point, we've talked mostly about a single stylesheet for our project
   background: blue;
 }
 ```
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 ## Stylesheet root
 
 Let's refactor the `player` class from out of our `game.st.css` to be in its own stylesheet.
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 ```css title="player.st.css"
 .root {
   -st-states: registered,
@@ -38,15 +38,15 @@ Let's refactor the `player` class from out of our `game.st.css` to be in its own
 }
 ```
 
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 We created a new `player.st.css` file above, and in it, created a new `.root` class. Then we moved the contents of the `.player` class rules to our new `root` class.
 
 :::info default root class
 In Stylable, each component stylesheet is represented by a `root` class that is automatically created, even if not explicitly defined by the user. This root class is expected to be applied to the [root element of the component](../../references/root.md#examples).
 :::
 
-<!-- TODO: might be nice to have an example component jsx here too -->
+{/* TODO: might be nice to have an example component jsx here too */}
 
 We can see that when we moved the `player` class, we also included its styling declarations. This might cause additional work in the future when trying to customize this class from the outside.
 
@@ -60,7 +60,7 @@ Keep in mind that, as we saw earlier in the [Namespacing chapter](./namespace.md
 
 Below, we import the `player.st.css` stylesheet and customize it by using the `@st-import` at-rule, and providing it with a **local name** for the default export (beginning with a capital letter) and a **request** to the target stylesheet. Then we move any customizations out of `player.st.css` into `game.st.css`.
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 ```css title="game.st.css - moved player customization"
 @st-import Player from "./player.st.css";
 
@@ -88,7 +88,7 @@ Player {
     </CodeBlock>
 </details>
 
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 ### Stylesheet root selector
 
@@ -98,7 +98,7 @@ It's important to note that a default import of a Stylable stylesheet represents
 
 By importing the default export of a stylesheet and then styling it, we are potentially customizing every instance of the component across our project. It is therefore **strongly recommended** to scope any selector that originates from a different namespace (stylesheet) or includes native elements with a local class.
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 ```css
 @st-import Player from "./player.st.css";
 
@@ -110,15 +110,15 @@ div {}
 .root Player {}
 .root div {}
 ```
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 :::
 
 ## Class named import
 
 For the next step, we would like to add `avatar` and `username` parts to `player.st.css`. These will be applied to the inner elements of the component, and are assumed to be nested under the `root` class.
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 ```css title="player.st.css - added avatar and username"
 .root {
   -st-states: registered,
@@ -127,11 +127,11 @@ For the next step, we would like to add `avatar` and `username` parts to `player
 .avatar {}
 .username {}
 ```
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 We then proceed to bind these new classes to their matching elements in the component.
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 ```jsx title="player.jsx - bind avatar and username"
 import { st, classes } from "./player.st.css";
 
@@ -144,11 +144,11 @@ const Player = ({ className }) => {
   )
 }
 ```
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 Now that we have these new classes, we can customize them externally through `game.st.css`. We do this by adding two `named imports`, inside square brackets, that link to our classes.
 
-<!-- prettier-ignore-start -->
+{/* prettier-ignore-start */}
 ```css title="game.st.css - player customization"
 @st-import Player, [avatar, username] from "./player.st.css";
 
@@ -179,7 +179,7 @@ Player .username {
     </CodeBlock>
 </details>
 
-<!-- prettier-ignore-end -->
+{/* prettier-ignore-end */}
 
 ### Validations
 

diff --git a/docs/references/cheatsheet.mdx b/docs/references/cheatsheet.mdx
@@ -21,14 +21,14 @@ Syntax that is unique to Stylable or extended from CSS.
 
 ### Selectors
 
-| Syntax                                                                     | Explanations                                                                        |
-| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| <CodeBlock language="css" className="inline-code">.x {}</CodeBlock>        | Class selector ([api](../references/class-selectors.md))                            |
-| <CodeBlock language="css" className="inline-code">x {}</CodeBlock>         | Element type selector ([api](../references/tag-selectors.md))                       |
-| <CodeBlock language="css" className="inline-code">:x {}</CodeBlock>        | Pseudo-class or custom state selector ([api](../references/pseudo-classes.md))      |
-| <CodeBlock language="css" className="inline-code">::x {}</CodeBlock>       | Pseudo-element or custom-element selector ([api](../references/pseudo-elements.md)) |
-| <CodeBlock language="css" className="inline-code">:--x {}</CodeBlock>      | custom selector ([api](../references/custom-selectors.md))                          |
-| <CodeBlock language="css" className="inline-code">:global() {}</CodeBlock> | disables selector namespacing ([api](../references/global-selectors.md))            |
+| Syntax                                                                         | Explanations                                                                        |
+| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| <CodeBlock language="css" className="inline-code">{'.x {}'}</CodeBlock>        | Class selector ([api](../references/class-selectors.md))                            |
+| <CodeBlock language="css" className="inline-code">{'x {}'}</CodeBlock>         | Element type selector ([api](../references/tag-selectors.md))                       |
+| <CodeBlock language="css" className="inline-code">{':x {}'}</CodeBlock>        | Pseudo-class or custom state selector ([api](../references/pseudo-classes.md))      |
+| <CodeBlock language="css" className="inline-code">{'::x {}'}</CodeBlock>       | Pseudo-element or custom-element selector ([api](../references/pseudo-elements.md)) |
+| <CodeBlock language="css" className="inline-code">{':--x {}'}</CodeBlock>      | custom selector ([api](../references/custom-selectors.md))                          |
+| <CodeBlock language="css" className="inline-code">{':global() {}'}</CodeBlock> | disables selector namespacing ([api](../references/global-selectors.md))            |
 
 ### Module system
 
@@ -40,7 +40,7 @@ Syntax that is unique to Stylable or extended from CSS.
 | <CodeBlock language="css" className="inline-code">@st-import [x as local-x] from './y.st.css';</CodeBlock>      | Local alias for named import ([api](../references/imports.md#local-alias)) |
 | <CodeBlock language="css" className="inline-code">@st-import [keyframes(x1, x2)] from './y.st.css';</CodeBlock> | Import keyframes ([api](../references/keyframes#import-and-export))        |
 | <CodeBlock language="css" className="inline-code">@st-import [layer(x1, x2)] from './y.st.css';</CodeBlock>     | Import layers ([api](../references/layer#import-and-export))               |
-| <CodeBlock language="css" className="inline-code">@st-import [container(x1, x2)] from './y.st.css';</CodeBlock> | Import containers ([api](../references/contains#import-and-export))            |
+| <CodeBlock language="css" className="inline-code">@st-import [container(x1, x2)] from './y.st.css';</CodeBlock> | Import containers ([api](../references/contains#import-and-export))        |
 
 ### Class extensions
 
@@ -53,15 +53,15 @@ Syntax that is unique to Stylable or extended from CSS.
 
 | Syntax                                                                                          | Explanations                                                                   |
 | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| <CodeBlock language="css" className="inline-code">:vars { x: red; y: blue; }</CodeBlock>        | Build time variables definition ([api](../references/variables.md#define))     |
+| <CodeBlock language="css" className="inline-code">{':vars { x: red; y: blue; }'}</CodeBlock>    | Build time variables definition ([api](../references/variables.md#define))     |
 | <CodeBlock language="css" className="inline-code">prop: value(x);</CodeBlock>                   | Insert var value into declaration ([api](../references/variables.md#evaluate)) |
 | <CodeBlock language="css" className="inline-code">prop: x(arg1, arg2);</CodeBlock>              | Computed value from custom formatter ([api](../references/formatters.md))      |
 | <CodeBlock language="css" className="inline-code">-st-mixin: x, y;</CodeBlock>                  | Apply multiple mixins to CSS ruleset ([api](../references/mixins.md))          |
 | <CodeBlock language="css" className="inline-code">-st-mixin: x(param v1, param v2);</CodeBlock> | Apply mixins with override params ([api](../references/mixins.md))             |
 
 ### Other
 
-| Syntax                                                                           | Explanations                                                                |
-| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| <CodeBlock language="css" className="inline-code">@st-scope .x {}</CodeBlock>    | Scope nested rules with a given selector ([api](../references/st-scope.md)) |
-| <CodeBlock language="css" className="inline-code">@st-namespace "x";</CodeBlock> | Development display name for debugging ([api](../references/namespace.md))  |
+| Syntax                                                                            | Explanations                                                                |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| <CodeBlock language="css" className="inline-code">{'@st-scope .x {}'}</CodeBlock> | Scope nested rules with a given selector ([api](../references/st-scope.md)) |
+| <CodeBlock language="css" className="inline-code">@st-namespace "x";</CodeBlock>  | Development display name for debugging ([api](../references/namespace.md))  |