chore: update tests

.eslintrc.cjs

@@ -92,17 +92,10 @@ module.exports = {
         '@typescript-eslint/member-delimiter-style': 'warn',
         '@typescript-eslint/method-signature-style': 'warn',
         '@typescript-eslint/no-extraneous-class': 'error',
-        '@typescript-eslint/no-redundant-type-constituents': 'off',
-        '@typescript-eslint/parameter-properties': 'error',
+        '@typescript-eslint/no-parameter-properties': 'error',
         '@typescript-eslint/strict-boolean-expressions': 'off'
       }
     },
-    {
-      files: ['**/*.cjs'],
-      env: {
-        node: true
-      }
-    },
     {
       extends: ['plugin:chai-expect/recommended', 'plugin:chai-friendly/recommended'],
       files: ['*.test.ts'],
@@ -186,17 +179,6 @@ module.exports = {
         ]
       }
     ],
-    'import/extensions': [
-      'error',
-      'always',
-      {
-        ignorePackages: true,
-        pattern: {
-          js: 'always',
-          ts: 'never'
-        }
-      }
-    ],
     'import/no-duplicates': 'warn',
     'sort-imports-es6-autofix/sort-imports-es6': [
       2,

.github/ISSUE_TEMPLATE/bug_report.md

@@ -3,7 +3,8 @@ name: Bug Report
 about: Create a bug report to help us fix a demonstrable problem with code in the library.
 title: ''
 labels: bug
-assignees: 
+assignees: claviska
+
 ---
 
 ### Describe the bug

.github/ISSUE_TEMPLATE/feature_request.md

@@ -3,6 +3,8 @@ name: Feature Request
 about: Suggest an idea for this project.
 title: ''
 labels: feature
+assignees: claviska
+
 ---
 
 ### What issue are you having?

.gitignore

@@ -1,9 +1,7 @@
-_site
-.cache
 .DS_Store
+.cache
+docs/dist
+docs/search.json
 dist
-docs/assets/images/sprite.svg
 node_modules
 src/react
-cdn
-web-types.json

.prettierignore

@@ -7,8 +7,5 @@ docs/search.json
 src/components/icon/icons
 src/react/index.ts
 node_modules
-package.json
 package-lock.json
 tsconfig.json
-cdn
-_site

README.md

@@ -51,7 +51,9 @@ Once you've cloned the repo, run the following command.
 npm start
 ```
 
-This will spin up the dev server. After the initial build, a browser will open automatically. There is currently no hot module reloading (HMR), as browser's don't provide a way to reregister custom elements, but most changes to the source will reload the browser automatically.
+This will spin up the Shoelace dev server. After the initial build, a browser will open automatically. There is currently no hot module reloading (HMR), as browser's don't provide a way to reregister custom elements, but most changes to the source will reload the browser automatically.
+
+The documentation is powered by Docsify, which uses raw markdown files to generate pages. As such, no static files are built for the docs.
 
 ### Building
 

cspell.json

@@ -18,7 +18,6 @@
     "CACHEABLE",
     "callout",
     "callouts",
-    "cdndir",
     "chatbubble",
     "checkmark",
     "claviska",
@@ -28,7 +27,6 @@
     "colocated",
     "colour",
     "combobox",
-    "Commonmark",
     "Composability",
     "Consolas",
     "contenteditable",
@@ -45,13 +43,11 @@
     "dogfood",
     "dropdowns",
     "easings",
-    "endraw",
     "enterkeyhint",
     "eqeqeq",
     "erroneou",
     "errormessage",
     "esbuild",
-    "exportmaps",
     "exportparts",
     "fieldsets",
     "formaction",
@@ -85,7 +81,6 @@
     "labelledby",
     "Laravel",
     "LaViska",
-    "linkify",
     "listbox",
     "listitem",
     "litelement",
@@ -99,7 +94,6 @@
     "minlength",
     "monospace",
     "mousedown",
-    "mousemove",
     "mouseup",
     "multiselectable",
     "nextjs",
@@ -107,13 +101,10 @@
     "noopener",
     "noreferrer",
     "novalidate",
-    "npmdir",
-    "Numberish",
     "outdir",
     "ParamagicDev",
     "peta",
     "petabit",
-    "prismjs",
     "progressbar",
     "radiogroup",
     "Railsbyte",
@@ -135,9 +126,7 @@
     "scroller",
     "Segoe",
     "semibold",
-    "sitedir",
     "slotchange",
-    "smartquotes",
     "spacebar",
     "stylesheet",
     "Tabbable",
@@ -153,14 +142,12 @@
     "tinycolor",
     "transitionend",
     "treeitem",
-    "treeshaking",
     "Triaging",
     "turbolinks",
     "typeof",
     "unbundles",
     "unbundling",
     "unicons",
-    "unsanitized",
     "unsupportive",
     "valpha",
     "valuenow",

custom-elements-manifest.config.js

@@ -1,6 +1,4 @@
-import * as path from 'path';
-import { customElementJetBrainsPlugin } from 'custom-element-jet-brains-integration';
-import { customElementVsCodePlugin } from 'custom-element-vs-code-integration';
+import { generateCustomData } from 'cem-plugin-vs-code-custom-data-generator';
 import { parse } from 'comment-parser';
 import { pascalCase } from 'pascal-case';
 import commandLineArgs from 'command-line-args';
@@ -28,7 +26,7 @@ function replace(string, terms) {
 }
 
 export default {
-  globs: ['src/components/**/*.component.ts'],
+  globs: ['src/components/**/*.ts'],
   exclude: ['**/*.styles.ts', '**/*.test.ts'],
   plugins: [
     // Append package data
@@ -38,34 +36,7 @@ export default {
         customElementsManifest.package = { name, description, version, author, homepage, license };
       }
     },
-    // Infer tag names because we no longer use @customElement decorators.
-    {
-      name: 'shoelace-infer-tag-names',
-      analyzePhase({ ts, node, moduleDoc }) {
-        switch (node.kind) {
-          case ts.SyntaxKind.ClassDeclaration: {
-            const className = node.name.getText();
-            const classDoc = moduleDoc?.declarations?.find(declaration => declaration.name === className);
 
-            const importPath = moduleDoc.path;
-
-            // This is kind of a best guess at components. "thing.component.ts"
-            if (!importPath.endsWith('.component.ts')) {
-              return;
-            }
-
-            const tagNameWithoutPrefix = path.basename(importPath, '.component.ts');
-            const tagName = 'sl-' + tagNameWithoutPrefix;
-
-            classDoc.tagNameWithoutPrefix = tagNameWithoutPrefix;
-            classDoc.tagName = tagName;
-
-            // This used to be set to true by @customElement
-            classDoc.customElement = true;
-          }
-        }
-      }
-    },
     // Parse custom jsDoc tags
     {
       name: 'shoelace-custom-tags',
@@ -87,9 +58,6 @@ export default {
               });
             });
 
-            // This is what allows us to map JSDOC comments to ReactWrappers.
-            classDoc['jsDoc'] = node.jsDoc?.map(jsDoc => jsDoc.getFullText()).join('\n');
-
             const parsed = parse(`${customComments}\n */`);
             parsed[0].tags?.forEach(t => {
               switch (t.tag) {
@@ -148,7 +116,6 @@ export default {
             if (classDoc?.events) {
               classDoc.events.forEach(event => {
                 event.reactName = `on${pascalCase(event.name)}`;
-                event.eventName = `${pascalCase(event.name)}Event`;
               });
             }
           }
@@ -170,7 +137,7 @@ export default {
           //
           const terms = [
             { from: /^src\//, to: '' }, // Strip the src/ prefix
-            { from: /\.component.(t|j)sx?$/, to: '.js' } // Convert .ts to .js
+            { from: /\.(t|j)sx?$/, to: '.js' } // Convert .ts to .js
           ];
 
           mod.path = replace(mod.path, terms);
@@ -192,24 +159,9 @@ export default {
       }
     },
     // Generate custom VS Code data
-    customElementVsCodePlugin({
+    generateCustomData({
       outdir,
-      cssFileName: null,
-      referencesTemplate: (_, tag) => [
-        {
-          name: 'Documentation',
-          url: `https://shoelace.style/components/${tag.replace('sl-', '')}`
-        }
-      ]
-    }),
-    customElementJetBrainsPlugin({
-      excludeCss: true,
-      referencesTemplate: (_, tag) => {
-        return {
-          name: 'Documentation',
-          url: `https://shoelace.style/components/${tag.replace('sl-', '')}`
-        };
-      }
+      cssFileName: null
     })
   ]
 };

docs/404.md

@@ -0,0 +1,5 @@
+# Not Found
+
+<img class="not-found-image" src="/assets/images/undraw-not-found.svg" alt="Cute monsters hiding behind a tree">
+
+Sorry, I couldn't find that page. Have you tried pressing <kbd>/</kbd> to search?

docs/_includes/component.njk

@@ -1,349 +0,0 @@
-{% extends "default.njk" %}
-
-{# Find the component based on the `tag` front matter #}
-{% set component = getComponent('sl-' + page.fileSlug) %}
-
-{% block content %}
-  {# Determine the badge variant #}
-  {% if component.status == 'stable' %}
-    {% set badgeVariant = 'primary' %}
-  {% elseif component.status == 'experimental' %}
-    {% set badgeVariant = 'warning' %}
-  {% elseif component.status == 'planned' %}
-    {% set badgeVariant = 'neutral' %}
-  {% elseif component.status == 'deprecated' %}
-    {% set badgeVariant = 'danger' %}
-  {% else %}
-    {% set badgeVariant = 'neutral' %}
-  {% endif %}
-
-  {# Header #}
-  <header class="component-header">
-    <h1>{{ component.name | classNameToComponentName }}</h1>
-
-    <div class="component-header__tag">
-      <code>&lt;{{ component.tagName }}&gt; | {{ component.name }}</code>
-    </div>
-
-    <div class="component-header__info">
-      <sl-badge variant="neutral" pill>
-        Since {{component.since or '?' }}
-      </sl-badge>
-      <sl-badge variant="{{ badgeVariant }}" pill style="text-transform: capitalize;">
-        {{ component.status }}
-      </sl-badge>
-    </div>
-  </header>
-
-  <p class="component-summary">
-    {% if component.summary %}
-      {{ component.summary | markdownInline | safe }}
-    {% endif %}
-  </p>
-
-  {# Markdown content #}
-  {{ content | safe }}
-
-  {# Importing #}
-  <h2>Importing</h2>
-  <p>
-    If you're using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use
-    any of the following snippets to <a href="/getting-started/installation#cherry-picking">cherry pick</a> this component.
-  </p>
-
-  <sl-tab-group>
-    <sl-tab slot="nav" panel="script">Script</sl-tab>
-    <sl-tab slot="nav" panel="import">Import</sl-tab>
-    <sl-tab slot="nav" panel="bundler">Bundler</sl-tab>
-    <sl-tab slot="nav" panel="react">React</sl-tab>
-
-    <sl-tab-panel name="script">
-      <p>
-        To import this component from <a href="https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace">the CDN</a>
-        using a script tag:
-      </p>
-      <pre><code class="language-html">&lt;script type=&quot;module&quot; src=&quot;https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@{{ meta.version }}/{{ meta.cdndir }}/{{ component.path }}&quot;&gt;&lt;/script&gt;</code></pre>
-    </sl-tab-panel>
-
-    <sl-tab-panel name="import">
-      <p>
-        To import this component from <a href="https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace">the CDN</a>
-        using a JavaScript import:
-      </p>
-      <pre><code class="language-js">import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@{{ meta.version }}/{{ meta.cdndir }}/{{ component.path }}';</code></pre>
-    </sl-tab-panel>
-
-    <sl-tab-panel name="bundler">
-      <p>
-        To import this component using <a href="{{ rootUrl('/getting-started/installation#bundling') }}">a bundler</a>:
-      </p>
-      <pre><code class="language-js">import '@shoelace-style/shoelace/{{ meta.npmdir }}/{{ component.path }}';</code></pre>
-    </sl-tab-panel>
-
-    <sl-tab-panel name="react">
-      <p>
-        To import this component as a <a href="/frameworks/react">React component</a>:
-      </p>
-      <pre><code class="language-js">import {{ component.name }} from '@shoelace-style/shoelace/{{ meta.npmdir }}/react/{{ component.tagNameWithoutPrefix }}';</code></pre>
-    </sl-tab-panel>
-  </sl-tab-group>
-
-  {# Slots #}
-  {% if component.slots.length %}
-    <h2>Slots</h2>
-
-    <table>
-      <thead>
-        <tr>
-          <th class="table-name">Name</th>
-          <th class="table-description">Description</th>
-        </tr>
-      </thead>
-      <tbody>
-        {% for slot in component.slots %}
-          <tr>
-            <td class="nowrap">
-              {% if slot.name %}
-                <code>{{ slot.name }}</code>
-              {% else %}
-                (default)
-              {% endif %}
-            </td>
-            <td>{{ slot.description | markdownInline | safe }}</td>
-          </tr>
-        {% endfor %}
-      </tbody>
-    </table>
-
-    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#slots') }}">using slots</a>.</em></p>
-  {% endif %}
-
-  {# Properties #}
-  {% if component.properties.length %}
-    <h2>Properties</h2>
-
-    <table>
-      <thead>
-        <tr>
-          <th class="table-name">Name</th>
-          <th class="table-description">Description</th>
-          <th class="table-reflects">Reflects</th>
-          <th class="table-type">Type</th>
-          <th class="table-default">Default</th>
-        </tr>
-      </thead>
-      <tbody>
-        {% for prop in component.properties %}
-          <tr>
-            <td>
-              <code class="nowrap">{{ prop.name }}</code>
-              {% if prop.attribute | length > 0 %}
-                {% if prop.attribute != prop.name %}
-                  <br>
-                  <sl-tooltip content="This attribute is different from its property">
-                    <small>
-                      <code class="nowrap">
-                        {{ prop.attribute }}
-                      </code>
-                    </small>
-                  </sl-tooltip>
-                {% endif %}
-              {% endif %}
-            </td>
-            <td>
-              {{ prop.description | markdownInline | safe }}
-            </td>
-            <td style="text-align: center;">
-              {% if prop.reflects %}
-                <sl-icon label="yes" name="check-lg"></sl-icon>
-              {% endif %}
-            </td>
-            <td>
-              {% if prop.type.text %}
-                <code>{{ prop.type.text | markdownInline | safe }}</code>
-              {% else %}
-                -
-              {% endif %}
-            </td>
-            <td>
-              {% if prop.default %}
-                <code>{{ prop.default | markdownInline | safe }}</code>
-              {% else %}
-                -
-              {% endif %}
-            </td>
-          </tr>
-        {% endfor %}
-        <tr>
-          <td class="nowrap"><code>updateComplete</code></td>
-          <td>
-            A read-only promise that resolves when the component has
-            <a href="/getting-started/usage?#component-rendering-and-updating">finished updating</a>.
-          </td>
-          <td></td>
-          <td></td>
-          <td></td>
-        </tr>
-      </tbody>
-    </table>
-
-    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#attributes-and-properties') }}">attributes and properties</a>.</em></p>
-  {% endif %}
-
-  {# Events #}
-  {% if component.events.length %}
-    <h2>Events</h2>
-
-    <table>
-      <thead>
-        <tr>
-          <th class="table-name" data-flavor="html">Name</th>
-          <th class="table-name" data-flavor="react">React Event</th>
-          <th class="table-description">Description</th>
-          <th class="table-event-detail">Event Detail</th>
-        </tr>
-      </thead>
-      <tbody>
-        {% for event in component.events %}
-          <tr>
-            <td data-flavor="html"><code class="nowrap">{{ event.name }}</code></td>
-            <td data-flavor="react"><code class="nowrap">{{ event.reactName }}</code></td>
-            <td>{{ event.description | markdownInline | safe }}</td>
-            <td>
-              {% if event.type.text %}
-                <code>{{ event.type.text }}</code>
-              {% else %}
-                -
-              {% endif %}
-            </td>
-          </tr>
-        {% endfor %}
-      </tbody>
-    </table>
-
-    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#events') }}">events</a>.</em></p>
-  {% endif %}
-
-  {# Methods #}
-  {% if component.methods.length %}
-    <h2>Methods</h2>
-
-    <table>
-      <thead>
-        <tr>
-          <th class="table-name">Name</th>
-          <th class="table-description">Description</th>
-          <th class="table-arguments">Arguments</th>
-        </tr>
-      </thead>
-      <tbody>
-        {% for method in component.methods %}
-          <tr>
-            <td class="nowrap"><code>{{ method.name }}()</code></td>
-            <td>{{ method.description | markdownInline | safe }}</td>
-            <td>
-              {% if method.parameters.length %}
-                <code>
-                  {% for param in method.parameters %}
-                    {{ param.name }}: {{ param.type.text }}{% if not loop.last %},{% endif %}
-                  {% endfor %}
-                </code>
-              {% else %}
-                -
-              {% endif %}
-            </td>
-          </tr>
-        {% endfor %}
-      </tbody>
-    </table>
-
-    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#methods') }}">methods</a>.</em></p>
-  {% endif %}
-
-  {# Custom Properties #}
-  {% if component.cssProperties.length %}
-    <h2>Custom Properties</h2>
-
-    <table>
-      <thead>
-        <tr>
-          <th class="table-name">Name</th>
-          <th class="table-description">Description</th>
-          <th class="table-default">Default</th>
-        </tr>
-      </thead>
-      <tbody>
-        {% for cssProperty in component.cssProperties %}
-          <tr>
-            <td class="nowrap"><code>{{ cssProperty.name }}</code></td>
-            <td>{{ cssProperty.description | markdownInline | safe }}</td>
-            <td>{{ cssProperty.default }}</td>
-          </tr>
-        {% endfor %}
-      </tbody>
-    </table>
-
-    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/usage#custom-properties') }}">customizing CSS custom properties</a>.</em></p>
-  {% endif %}
-
-  {# CSS Parts #}
-  {% if component.cssParts.length %}
-    <h2>Parts</h2>
-
-    <table>
-      <thead>
-        <tr>
-          <th class="table-name">Name</th>
-          <th class="table-description">Description</th>
-        </tr>
-      </thead>
-      <tbody>
-        {% for cssPart in component.cssParts %}
-          <tr>
-            <td class="nowrap"><code>{{ cssPart.name }}</code></td>
-            <td>{{ cssPart.description | markdownInline | safe }}</td>
-          </tr>
-        {% endfor %}
-      </tbody>
-    </table>
-
-    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/customizing/#css-parts') }}">customizing CSS parts</a>.</em></p>
-  {% endif %}
-
-  {# Animations #}
-  {% if component.animations.length %}
-    <h2>Animations</h2>
-
-    <table>
-      <thead>
-        <tr>
-          <th class="table-name">Name</th>
-          <th class="table-description">Description</th>
-        </tr>
-      </thead>
-      <tbody>
-        {% for animation in component.animations %}
-          <tr>
-            <td class="nowrap"><code>{{ animation.name }}</code></td>
-            <td>{{ animation.description | markdownInline | safe }}</td>
-          </tr>
-        {% endfor %}
-      </tbody>
-    </table>
-
-    <p><em>Learn more about <a href="{{ rootUrl('/getting-started/customizing#animations') }}">customizing animations</a>.</em></p>
-  {% endif %}
-
-  {# Dependencies #}
-  {% if component.dependencies.length %}
-    <h2>Dependencies</h2>
-
-    <p>This component automatically imports the following dependencies.</p>
-
-    <ul>
-      {% for dependency in component.dependencies %}
-        <li><code>&lt;{{ dependency }}&gt;</code></li>
-      {% endfor %}
-    </ul>
-  {% endif %}
-{% endblock %}

docs/_includes/default.njk

@@ -1,150 +0,0 @@
-<!DOCTYPE html>
-<html
-  lang="en"
-  data-layout="{{ layout }}"
-  data-shoelace-version="{{ meta.version }}"
->
-  <head>
-    {# Metadata #}
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="description" content="{{ meta.description }}" />
-    <title>{{ meta.title }}</title>
-
-    {# Opt out of Turbo caching #}
-    <meta name="turbo-cache-control">
-
-    {# Stylesheets #}
-    <link rel="stylesheet" href="{{ assetUrl('styles/docs.css') }}" />
-    <link rel="stylesheet" href="{{ assetUrl('styles/code-previews.css') }}" />
-    <link rel="stylesheet" href="{{ assetUrl('styles/search.css') }}" />
-
-    {# Favicons #}
-    <link rel="icon" href="{{ assetUrl('images/logo.svg') }}" type="image/x-icon" />
-
-    {# Twitter Cards #}
-    <meta name="twitter:card" content="summary" />
-    <meta name="twitter:creator" content="shoelace_style" />
-    <meta name="twitter:image" content="{{ assetUrl(meta.image, true) }}" />
-
-    {# OpenGraph #}
-    <meta property="og:url" content="{{ rootUrl(page.url, true) }}" />
-    <meta property="og:title" content="{{ meta.title }}" />
-    <meta property="og:description" content="{{ meta.description }}" />
-    <meta property="og:image" content="{{ assetUrl(meta.image, true) }}" />
-
-    {# Shoelace #}
-    <link rel="stylesheet" href="/dist/themes/light.css" />
-    <link rel="stylesheet" href="/dist/themes/dark.css" />
-    <script type="module" src="/dist/shoelace-autoloader.js"></script>
-
-    {# Set the initial theme and menu states here to prevent flashing #}
-    <script>
-      (() => {
-        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-        const theme = localStorage.getItem('theme') || 'auto';
-        document.documentElement.classList.toggle('sl-theme-dark', theme === 'dark' || (theme === 'auto' && prefersDark));
-      })();
-    </script>
-
-    {# Turbo + Scroll positioning #}
-    <script src="{{ assetUrl('scripts/turbo.js') }}" type="module"></script>
-    <script src="{{ assetUrl('scripts/docs.js') }}" defer></script>
-    <script src="{{ assetUrl('scripts/code-previews.js') }}" defer></script>
-    <script src="{{ assetUrl('scripts/lunr.js') }}" defer></script>
-    <script src="{{ assetUrl('scripts/search.js') }}" defer></script>
-  </head>
-  <body>
-    <a id="skip-to-main" class="visually-hidden" href="#main-content" data-smooth-link="false">
-      Skip to main content
-    </a>
-
-    {# Menu toggle #}
-    <button id="menu-toggle" type="button" aria-label="Menu">
-      <svg width="148" height="148" viewBox="0 0 148 148" xmlns="http://www.w3.org/2000/svg">
-        <g stroke="currentColor" stroke-width="18" fill="none" fill-rule="evenodd" stroke-linecap="round">
-          <path d="M9.5 125.5h129M9.5 74.5h129M9.5 23.5h129"></path>
-        </g>
-      </svg>
-    </button>
-
-    {# Icon toolbar #}
-    <div id="icon-toolbar">
-      {# GitHub #}
-      <a href="https://github.com/shoelace-style/shoelace" title="View Shoelace on GitHub">
-        <sl-icon name="github"></sl-icon>
-      </a>
-
-      {# Twitter #}
-      <a href="https://twitter.com/shoelace_style" title="Follow Shoelace on Twitter">
-        <sl-icon name="twitter"></sl-icon>
-      </a>
-
-      {# Theme selector #}
-      <sl-dropdown id="theme-selector" placement="bottom-end" distance="3">
-        <sl-button slot="trigger" size="small" variant="text" caret title="Press \ to toggle">
-          <sl-icon class="only-light" name="sun-fill"></sl-icon>
-          <sl-icon class="only-dark" name="moon-fill"></sl-icon>
-        </sl-button>
-        <sl-menu>
-          <sl-menu-item type="checkbox" value="light">Light</sl-menu-item>
-          <sl-menu-item type="checkbox" value="dark">Dark</sl-menu-item>
-          <sl-divider></sl-divider>
-          <sl-menu-item type="checkbox" value="auto">System</sl-menu-item>
-        </sl-menu>
-      </sl-dropdown>
-    </div>
-
-    <aside id="sidebar" data-preserve-scroll>
-      <header>
-        <a href="/">
-          <img src="{{ assetUrl('images/wordmark.svg') }}" alt="Shoelace" />
-        </a>
-        <div class="sidebar-version">
-          {{ meta.version }}
-        </div>
-      </header>
-
-      <div class="sidebar-buttons">
-        <sl-button size="small" class="repo-button repo-button--github" href="https://github.com/shoelace-style/shoelace" target="_blank">
-          <sl-icon slot="prefix" name="github"></sl-icon> Code
-        </sl-button>
-        <sl-button size="small" class="repo-button repo-button--star" href="https://github.com/shoelace-style/shoelace/stargazers" target="_blank">
-          <sl-icon slot="prefix" name="star-fill"></sl-icon> Star
-        </sl-button>
-        <sl-button size="small" class="repo-button repo-button--twitter" href="https://twitter.com/shoelace_style" target="_blank">
-          <sl-icon slot="prefix" name="twitter"></sl-icon> Follow
-        </sl-button>
-      </div>
-
-      <button class="search-box" type="button" title="Press / to search" aria-label="Search" data-plugin="search">
-        <sl-icon name="search"></sl-icon>
-        <span>Search</span>
-      </button>
-
-      <nav>
-        {% include 'sidebar.njk' %}
-      </nav>
-    </aside>
-
-    {# Content #}
-    <main>
-      <a id="main-content"></a>
-      <article id="content" class="content{% if toc %} content--with-toc{% endif %}">
-        {% if toc %}
-          <div class="content__toc">
-            <ul>
-              <li class="top"><a href="#">{{ meta.title }}</a></li>
-            </ul>
-          </div>
-        {% endif %}
-
-        <div class="content__body">
-          {% block content %}
-            {{ content | safe }}
-          {% endblock %}
-        </div>
-      </article>
-    </main>
-  </body>
-</html>

docs/_includes/sidebar.njk

@@ -1,65 +0,0 @@
-<ul>
-  <li>
-    <h2>Getting Started</h2>
-    <ul>
-      <li><a href="/">Home</a></li>
-      <li><a href="/getting-started/installation">Installation</a></li>
-      <li><a href="/getting-started/usage">Usage</a></li>
-      <li><a href="/getting-started/themes">Themes</a></li>
-      <li><a href="/getting-started/customizing">Customizing</a></li>
-      <li><a href="/getting-started/form-controls">Form Controls</a></li>
-      <li><a href="/getting-started/localization">Localization</a></li>
-    </ul>
-  </li>
-  <li>
-    <h2>Frameworks</h2>
-    <ul>
-      <li><a href="/frameworks/react">React</a></li>
-      <li><a href="/frameworks/vue">Vue</a></li>
-      <li><a href="/frameworks/angular">Angular</a></li>
-    </ul>
-  </li>
-  <li>
-    <h2>Resources</h2>
-    <ul>
-      <li><a href="/resources/community">Community</a></li>
-      <li><a href="https://github.com/shoelace-style/shoelace/discussions">Help &amp; Support</a></li>
-      <li><a href="/resources/accessibility">Accessibility</a></li>
-      <li><a href="/resources/contributing">Contributing</a></li>
-      <li><a href="/resources/changelog">Changelog</a></li>
-    </ul>
-  </li>
-  <li>
-    <h2>Components</h2>
-    <ul>
-      {% for component in meta.components %}
-        <li>
-          <a href="/components/{{ component.tagName | removeSlPrefix }}">
-            {{ component.name | classNameToComponentName }}
-          </a>
-        </li>
-      {% endfor %}
-    </ul>
-  </li>
-  <li>
-    <h2>Design Tokens</h2>
-    <ul>
-      <li><a href="/tokens/typography">Typography</a></li>
-      <li><a href="/tokens/color">Color</a></li>
-      <li><a href="/tokens/spacing">Spacing</a></li>
-      <li><a href="/tokens/elevation">Elevation</a></li>
-      <li><a href="/tokens/border-radius">Border Radius</a></li>
-      <li><a href="/tokens/transition">Transition</a></li>
-      <li><a href="/tokens/z-index">Z-index</a></li>
-      <li><a href="/tokens/more">More Tokens</a></li>
-    </ul>
-  </li>
-  <li>
-    <h2>Tutorials</h2>
-    <ul>
-      <li><a href="/tutorials/integrating-with-laravel">Integrating with Laravel</a></li>
-      <li><a href="/tutorials/integrating-with-nextjs">Integrating with NextJS</a></li>
-      <li><a href="/tutorials/integrating-with-rails">Integrating with Rails</a></li>
-    </ul>
-  </li>
-</ul>

docs/_sidebar.md

@@ -0,0 +1,103 @@
+- Getting Started
+
+  - [Overview](/)
+  - [Installation](/getting-started/installation)
+  - [Usage](/getting-started/usage)
+  - [Themes](/getting-started/themes)
+  - [Customizing](/getting-started/customizing)
+  - [Form Controls](/getting-started/form-controls)
+  - [Localization](/getting-started/localization)
+
+- Frameworks
+
+  - [React](/frameworks/react)
+  - [Vue](/frameworks/vue)
+  - [Angular](/frameworks/angular)
+
+- Resources
+
+  - [Community](/resources/community)
+  - [Accessibility](/resources/accessibility)
+  - [Contributing](/resources/contributing)
+  - [Changelog](/resources/changelog)
+
+- Components
+
+  - [Alert](/components/alert)
+  - [Avatar](/components/avatar)
+  - [Badge](/components/badge)
+  - [Breadcrumb](/components/breadcrumb)
+  - [Breadcrumb Item](/components/breadcrumb-item)
+  - [Button](/components/button)
+  - [Button Group](/components/button-group)
+  - [Card](/components/card)
+  - [Carousel](/components/carousel)
+  - [Carousel Item](/components/carousel-item)
+  - [Checkbox](/components/checkbox)
+  - [Color Picker](/components/color-picker)
+  - [Details](/components/details)
+  - [Dialog](/components/dialog)
+  - [Divider](/components/divider)
+  - [Drawer](/components/drawer)
+  - [Dropdown](/components/dropdown)
+  - [Icon](/components/icon)
+  - [Icon Button](/components/icon-button)
+  - [Image Comparer](/components/image-comparer)
+  - [Input](/components/input)
+  - [Menu](/components/menu)
+  - [Menu Item](/components/menu-item)
+  - [Menu Label](/components/menu-label)
+  - [Option](/components/option)
+  - [Progress Bar](/components/progress-bar)
+  - [Progress Ring](/components/progress-ring)
+  - [QR Code](/components/qr-code)
+  - [Radio](/components/radio)
+  - [Radio Button](/components/radio-button)
+  - [Radio Group](/components/radio-group)
+  - [Range](/components/range)
+  - [Rating](/components/rating)
+  - [Select](/components/select)
+  - [Skeleton](/components/skeleton)
+  - [Spinner](/components/spinner)
+  - [Split Panel](/components/split-panel)
+  - [Switch](/components/switch)
+  - [Tab Group](/components/tab-group)
+  - [Tab](/components/tab)
+  - [Tab Panel](/components/tab-panel)
+  - [Tag](/components/tag)
+  - [Textarea](/components/textarea)
+  - [Tooltip](/components/tooltip)
+  - [Tree](/components/tree)
+  - [Tree Item](/components/tree-item)
+  <!--plop:component-->
+
+- Utilities
+
+  - [Animated Image](/components/animated-image)
+  - [Animation](/components/animation)
+  - [Format Bytes](/components/format-bytes)
+  - [Format Date](/components/format-date)
+  - [Format Number](/components/format-number)
+  - [Include](/components/include)
+  - [Mutation Observer](/components/mutation-observer)
+  - [Popup](/components/popup)
+  - [Relative Time](/components/relative-time)
+  - [Resize Observer](/components/resize-observer)
+  - [Visually Hidden](/components/visually-hidden)
+
+- Design Tokens
+
+  - [Typography](/tokens/typography)
+  - [Color](/tokens/color)
+  - [Spacing](/tokens/spacing)
+  - [Elevation](/tokens/elevation)
+  - [Border Radius](/tokens/border-radius)
+  - [Transition](/tokens/transition)
+  - [Z-index](/tokens/z-index)
+  - [More](/tokens/more)
+
+- Tutorials
+
+  - [Integrating with Laravel](/tutorials/integrating-with-laravel)
+  - [Integrating with NextJS](/tutorials/integrating-with-nextjs)
+  - [Integrating with Rails](/tutorials/integrating-with-rails)

docs/_utilities/active-links.cjs

@@ -1,35 +0,0 @@
-function normalizePathname(pathname) {
-  // Remove /index.html
-  if (pathname.endsWith('/index.html')) {
-    pathname = pathname.replace(/\/index\.html/, '');
-  }
-
-  // Remove trailing slashes
-  return pathname.replace(/\/$/, '');
-}
-
-/**
- * Adds a class name to links that are currently active.
- */
-module.exports = function (doc, options) {
-  options = {
-    className: 'active-link', // the class to add to active links
-    pathname: undefined, // the current pathname to compare
-    within: 'body', // element containing the target links
-    ...options
-  };
-
-  const within = doc.querySelector(options.within);
-
-  if (!within) {
-    return doc;
-  }
-
-  within.querySelectorAll('a').forEach(link => {
-    if (normalizePathname(options.pathname) === normalizePathname(link.pathname)) {
-      link.classList.add(options.className);
-    }
-  });
-
-  return doc;
-};

docs/_utilities/anchor-headings.cjs

@@ -1,64 +0,0 @@
-const { createSlug } = require('./strings.cjs');
-
-/**
- * Turns headings into clickable, deep linkable anchors. The provided doc should be a document object provided by JSDOM.
- * The same document will be returned with the appropriate DOM manipulations.
- */
-module.exports = function (doc, options) {
-  options = {
-    levels: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'], // the headings to convert
-    className: 'anchor-heading', // the class name to add
-    within: 'body', // the element containing the target headings
-    ...options
-  };
-
-  const within = doc.querySelector(options.within);
-
-  if (!within) {
-    return doc;
-  }
-
-  within.querySelectorAll('h1, h2, h3, h4, h5, h6').forEach(heading => {
-    const hasAnchor = heading.querySelector('a');
-    const anchor = doc.createElement('a');
-    let id = heading.textContent ?? '';
-    let suffix = 0;
-
-    // Skip heading levels we don't care about
-    if (!options.levels?.includes(heading.tagName.toLowerCase())) {
-      return;
-    }
-
-    // Convert dots to underscores
-    id = id.replace(/\./g, '_');
-
-    // Turn it into a slug
-    id = createSlug(id);
-
-    // Make sure it starts with a letter
-    if (!/^[a-z]/i.test(id)) {
-      id = `id_${id}`;
-    }
-
-    // Make sure the id is unique
-    const originalId = id;
-    while (doc.getElementById(id) !== null) {
-      id = `${originalId}-${++suffix}`;
-    }
-
-    if (hasAnchor || !id) return;
-
-    heading.setAttribute('id', id);
-    anchor.setAttribute('href', `#${encodeURIComponent(id)}`);
-    anchor.setAttribute('aria-label', `Direct link to "${heading.textContent}"`);
-
-    if (options.className) {
-      heading.classList.add(options.className);
-    }
-
-    // Append the anchor
-    heading.append(anchor);
-  });
-
-  return doc;
-};

docs/_utilities/cem.cjs

@@ -1,71 +0,0 @@
-const customElementsManifest = require('../../dist/custom-elements.json');
-
-//
-// Export it here so we can import it elsewhere and use the same version
-//
-module.exports.customElementsManifest = customElementsManifest;
-
-//
-// Gets all components from custom-elements.json and returns them in a more documentation-friendly format.
-//
-module.exports.getAllComponents = function () {
-  const allComponents = [];
-
-  customElementsManifest.modules?.forEach(module => {
-    module.declarations?.forEach(declaration => {
-      if (declaration.customElement) {
-        // Generate the dist path based on the src path and attach it to the component
-        declaration.path = module.path.replace(/^src\//, 'dist/').replace(/\.ts$/, '.js');
-
-        // Remove members that are private or don't have a description
-        const members = declaration.members?.filter(member => member.description && member.privacy !== 'private');
-        const methods = members?.filter(prop => prop.kind === 'method' && prop.privacy !== 'private');
-        const properties = members?.filter(prop => {
-          // Look for a corresponding attribute
-          const attribute = declaration.attributes?.find(attr => attr.fieldName === prop.name);
-          if (attribute) {
-            prop.attribute = attribute.name || attribute.fieldName;
-          }
-
-          return prop.kind === 'field' && prop.privacy !== 'private';
-        });
-        allComponents.push({
-          ...declaration,
-          methods,
-          properties
-        });
-      }
-    });
-  });
-
-  // Build dependency graphs
-  allComponents.forEach(component => {
-    const dependencies = [];
-
-    // Recursively fetch sub-dependencies
-    function getDependencies(tag) {
-      const cmp = allComponents.find(c => c.tagName === tag);
-      if (!cmp || !Array.isArray(component.dependencies)) {
-        return;
-      }
-
-      cmp.dependencies?.forEach(dependentTag => {
-        if (!dependencies.includes(dependentTag)) {
-          dependencies.push(dependentTag);
-        }
-        getDependencies(dependentTag);
-      });
-    }
-
-    getDependencies(component.tagName);
-
-    component.dependencies = dependencies.sort();
-  });
-
-  // Sort by name
-  return allComponents.sort((a, b) => {
-    if (a.name < b.name) return -1;
-    if (a.name > b.name) return 1;
-    return 0;
-  });
-};

docs/_utilities/code-previews.cjs

@@ -1,138 +0,0 @@
-let count = 1;
-
-function escapeHtml(str) {
-  return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-}
-
-/**
- * Turns code fields with the :preview suffix into interactive code previews.
- */
-module.exports = function (doc, options) {
-  options = {
-    within: 'body', // the element containing the code fields to convert
-    ...options
-  };
-
-  const within = doc.querySelector(options.within);
-  if (!within) {
-    return doc;
-  }
-
-  within.querySelectorAll('[class*=":preview"]').forEach(code => {
-    const pre = code.closest('pre');
-    if (!pre) {
-      return;
-    }
-    const adjacentPre = pre.nextElementSibling?.tagName.toLowerCase() === 'pre' ? pre.nextElementSibling : null;
-    const reactCode = adjacentPre?.querySelector('code[class$="react"]');
-    const sourceGroupId = `code-preview-source-group-${count}`;
-    const isExpanded = code.getAttribute('class').includes(':expanded');
-    const noCodePen = code.getAttribute('class').includes(':no-codepen');
-
-    count++;
-
-    const htmlButton = `
-      <button type="button"
-        title="Show HTML code"
-        class="code-preview__button code-preview__button--html"
-      >
-        HTML
-      </button>
-    `;
-
-    const reactButton = `
-      <button type="button" title="Show React code" class="code-preview__button code-preview__button--react">
-        React
-      </button>
-    `;
-
-    const codePenButton = `
-      <button type="button" class="code-preview__button code-preview__button--codepen" title="Edit on CodePen">
-        <svg
-          width="138"
-          height="26"
-          viewBox="0 0 138 26"
-          fill="none"
-          stroke="currentColor"
-          stroke-width="2.3"
-          stroke-linecap="round"
-          stroke-linejoin="round"
-        >
-          <path d="M80 6h-9v14h9 M114 6h-9 v14h9 M111 13h-6 M77 13h-6 M122 20V6l11 14V6 M22 16.7L33 24l11-7.3V9.3L33 2L22 9.3V16.7z M44 16.7L33 9.3l-11 7.4 M22 9.3l11 7.3 l11-7.3 M33 2v7.3 M33 16.7V24 M88 14h6c2.2 0 4-1.8 4-4s-1.8-4-4-4h-6v14 M15 8c-1.3-1.3-3-2-5-2c-4 0-7 3-7 7s3 7 7 7 c2 0 3.7-0.8 5-2 M64 13c0 4-3 7-7 7h-5V6h5C61 6 64 9 64 13z" />
-        </svg>
-      </button>
-    `;
-
-    const codePreview = `
-      <div class="code-preview ${isExpanded ? 'code-preview--expanded' : ''}">
-        <div class="code-preview__preview">
-          ${code.textContent}
-          <div class="code-preview__resizer">
-            <sl-icon name="grip-vertical"></sl-icon>
-          </div>
-        </div>
-
-        <div class="code-preview__source-group" id="${sourceGroupId}">
-          <div class="code-preview__source code-preview__source--html" ${reactCode ? 'data-flavor="html"' : ''}>
-            <pre><code class="language-html">${escapeHtml(code.textContent)}</code></pre>
-          </div>
-
-          ${
-            reactCode
-              ? `
-            <div class="code-preview__source code-preview__source--react" data-flavor="react">
-              <pre><code class="language-jsx">${escapeHtml(reactCode.textContent)}</code></pre>
-            </div>
-          `
-              : ''
-          }
-        </div>
-
-        <div class="code-preview__buttons">
-          <button
-            type="button"
-            class="code-preview__button code-preview__toggle"
-            aria-expanded="${isExpanded ? 'true' : 'false'}"
-            aria-controls="${sourceGroupId}"
-          >
-            Source
-            <svg
-              viewBox="0 0 24 24"
-              fill="none"
-              stroke="currentColor"
-              stroke-width="2"
-              stroke-linecap="round"
-              stroke-linejoin="round"
-            >
-              <polyline points="6 9 12 15 18 9"></polyline>
-            </svg>
-          </button>
-
-          ${reactCode ? ` ${htmlButton} ${reactButton} ` : ''}
-
-          ${noCodePen ? '' : codePenButton}
-        </div>
-      </div>
-    `;
-
-    pre.insertAdjacentHTML('afterend', codePreview);
-    pre.remove();
-
-    if (adjacentPre) {
-      adjacentPre.remove();
-    }
-  });
-
-  // Wrap code preview scripts in anonymous functions so they don't run in the global scope
-  doc.querySelectorAll('.code-preview__preview script').forEach(script => {
-    if (script.type === 'module') {
-      // Modules are already scoped
-      script.textContent = script.innerHTML;
-    } else {
-      // Wrap non-modules in an anonymous function so they don't run in the global scope
-      script.textContent = `(() => { ${script.innerHTML} })();`;
-    }
-  });
-
-  return doc;
-};

docs/_utilities/copy-code-buttons.cjs

@@ -1,23 +0,0 @@
-let codeBlockId = 0;
-
-/**
- * Adds copy code buttons to code fields. The provided doc should be a document object provided by JSDOM. The same
- * document will be returned with the appropriate DOM manipulations.
- */
-module.exports = function (doc) {
-  doc.querySelectorAll('pre > code').forEach(code => {
-    const pre = code.closest('pre');
-    const button = doc.createElement('sl-copy-button');
-
-    if (!code.id) {
-      code.id = `code-block-${++codeBlockId}`;
-    }
-
-    button.classList.add('copy-code-button');
-    button.setAttribute('from', code.id);
-
-    pre.append(button);
-  });
-
-  return doc;
-};

docs/_utilities/external-links.cjs

@@ -1,41 +0,0 @@
-const { isExternalLink } = require('./strings.cjs');
-
-/**
- * Transforms external links to make them safer and optionally add a target. The provided doc should be a document
- * object provided by JSDOM. The same document will be returned with the appropriate DOM manipulations.
- */
-module.exports = function (doc, options) {
-  options = {
-    className: 'external-link', // the class name to add to links
-    noopener: true, // sets rel="noopener"
-    noreferrer: true, // sets rel="noreferrer"
-    ignore: () => false, // callback function to filter links that should be ignored
-    within: 'body', // element that contains the target links
-    target: '', // sets the target attribute
-    ...options
-  };
-
-  const within = doc.querySelector(options.within);
-
-  if (within) {
-    within.querySelectorAll('a').forEach(link => {
-      if (isExternalLink(link) && !options.ignore(link)) {
-        link.classList.add(options.className);
-
-        const rel = [];
-        if (options.noopener) rel.push('noopener');
-        if (options.noreferrer) rel.push('noreferrer');
-
-        if (rel.length) {
-          link.setAttribute('rel', rel.join(' '));
-        }
-
-        if (options.target) {
-          link.setAttribute('target', options.target);
-        }
-      }
-    });
-  }
-
-  return doc;
-};

docs/_utilities/highlight-code.cjs

@@ -1,63 +0,0 @@
-const Prism = require('prismjs');
-const PrismLoader = require('prismjs/components/index.js');
-
-PrismLoader('diff');
-PrismLoader.silent = true;
-
-/** Highlights a code string. */
-function highlight(code, language) {
-  const alias = language.replace(/^diff-/, '');
-  const isDiff = /^diff-/i.test(language);
-
-  // Auto-load the target language
-  if (!Prism.languages[alias]) {
-    PrismLoader(alias);
-
-    if (!Prism.languages[alias]) {
-      throw new Error(`Unsupported language for code highlighting: "${language}"`);
-    }
-  }
-
-  // Register diff-* languages to use the diff grammar
-  if (isDiff) {
-    Prism.languages[language] = Prism.languages.diff;
-  }
-
-  return Prism.highlight(code, Prism.languages[language], language);
-}
-
-/**
- * Highlights all code fields that have a language parameter. If the language has a colon in its name, the first chunk
- * will be the language used and additional chunks will be applied as classes to the `<pre>`. For example, a code field
- * tagged with "html:preview" will be rendered as `<pre class="language-html preview">`.
- *
- * The provided doc should be a document object provided by JSDOM. The same document will be returned with the
- * appropriate DOM manipulations.
- */
-module.exports = function (doc) {
-  doc.querySelectorAll('pre > code[class]').forEach(code => {
-    // Look for class="language-*" and split colons into separate classes
-    code.classList.forEach(className => {
-      if (className.startsWith('language-')) {
-        //
-        // We use certain suffixes to indicate code previews, expanded states, etc. The class might look something like
-        // this:
-        //
-        //  class="language-html:preview:expanded"
-        //
-        // The language will always come first, so we need to drop the "language-" prefix and everything after the first
-        // color to get the highlighter language.
-        //
-        const language = className.replace(/^language-/, '').split(':')[0];
-
-        try {
-          code.innerHTML = highlight(code.textContent ?? '', language);
-        } catch (err) {
-          // Language not found, skip it
-        }
-      }
-    });
-  });
-
-  return doc;
-};

docs/_utilities/markdown.cjs

@@ -1,67 +0,0 @@
-const MarkdownIt = require('markdown-it');
-const markdownItContainer = require('markdown-it-container');
-const markdownItIns = require('markdown-it-ins');
-const markdownItKbd = require('markdown-it-kbd');
-const markdownItMark = require('markdown-it-mark');
-const markdownItReplaceIt = require('markdown-it-replace-it');
-
-const markdown = MarkdownIt({
-  html: true,
-  xhtmlOut: false,
-  breaks: false,
-  langPrefix: 'language-',
-  linkify: false,
-  typographer: false
-});
-
-// Third-party plugins
-markdown.use(markdownItContainer);
-markdown.use(markdownItIns);
-markdown.use(markdownItKbd);
-markdown.use(markdownItMark);
-markdown.use(markdownItReplaceIt);
-
-// Callouts
-['tip', 'warning', 'danger'].forEach(type => {
-  markdown.use(markdownItContainer, type, {
-    render: function (tokens, idx) {
-      if (tokens[idx].nesting === 1) {
-        return `<div role="alert" class="callout callout--${type}">`;
-      }
-      return '</div>\n';
-    }
-  });
-});
-
-// Asides
-markdown.use(markdownItContainer, 'aside', {
-  render: function (tokens, idx) {
-    if (tokens[idx].nesting === 1) {
-      return `<aside>`;
-    }
-    return '</aside>\n';
-  }
-});
-
-// Details
-markdown.use(markdownItContainer, 'details', {
-  validate: params => params.trim().match(/^details\s+(.*)$/),
-  render: (tokens, idx) => {
-    const m = tokens[idx].info.trim().match(/^details\s+(.*)$/);
-    if (tokens[idx].nesting === 1) {
-      return `<details>\n<summary><span>${markdown.utils.escapeHtml(m[1])}</span></summary>\n`;
-    }
-    return '</details>\n';
-  }
-});
-
-// Replace [#1234] with a link to GitHub issues
-markdownItReplaceIt.replacements.push({
-  name: 'github-issues',
-  re: /\[#([0-9]+)\]/gs,
-  sub: '<a href="https://github.com/shoelace-style/shoelace/issues/$1">#$1</a>',
-  html: true,
-  default: true
-});
-
-module.exports = markdown;

docs/_utilities/prettier.cjs

@@ -1,26 +0,0 @@
-const { format } = require('prettier');
-
-/** Formats markup using prettier. */
-module.exports = function (content, options) {
-  options = {
-    arrowParens: 'avoid',
-    bracketSpacing: true,
-    htmlWhitespaceSensitivity: 'css',
-    insertPragma: false,
-    bracketSameLine: false,
-    jsxSingleQuote: false,
-    parser: 'html',
-    printWidth: 120,
-    proseWrap: 'preserve',
-    quoteProps: 'as-needed',
-    requirePragma: false,
-    semi: true,
-    singleQuote: true,
-    tabWidth: 2,
-    trailingComma: 'none',
-    useTabs: false,
-    ...options
-  };
-
-  return format(content, options);
-};

docs/_utilities/replacer.cjs

@@ -1,19 +0,0 @@
-/**
- * @typedef {object} Replacement
- * @property {string | RegExp} pattern
- * @property {string} replacement
- */
-
-/**
- * @typedef {Array<Replacement>} Replacements
- */
-
-/**
- * @param {Document} content
- * @param {Replacements} replacements
- */
-module.exports = function (content, replacements) {
-  replacements.forEach(replacement => {
-    content.body.innerHTML = content.body.innerHTML.replaceAll(replacement.pattern, replacement.replacement);
-  });
-};

docs/_utilities/scrolling-tables.cjs

@@ -1,21 +0,0 @@
-/**
- * Turns headings into clickable, deep linkable anchors. The provided doc should be a document object provided by JSDOM.
- * The same document will be returned with the appropriate DOM manipulations.
- */
-module.exports = function (doc, options) {
-  const tables = [...doc.querySelectorAll('table')];
-
-  options = {
-    className: 'table-scroll', // the class name to add to the table's container
-    ...options
-  };
-
-  tables.forEach(table => {
-    const div = doc.createElement('div');
-    div.classList.add(options.className);
-    table.insertAdjacentElement('beforebegin', div);
-    div.append(table);
-  });
-
-  return doc;
-};

docs/_utilities/strings.cjs

@@ -1,16 +0,0 @@
-const slugify = require('slugify');
-
-/** Creates a slug from an arbitrary string of text. */
-module.exports.createSlug = function (text) {
-  return slugify(String(text), {
-    remove: /[^\w|\s]/g,
-    lower: true
-  });
-};
-
-/** Determines whether or not a link is external. */
-module.exports.isExternalLink = function (link) {
-  // We use the "internal" hostname when initializing JSDOM so we know that those are local links
-  if (!link.hostname || link.hostname === 'internal') return false;
-  return true;
-};

docs/_utilities/table-of-contents.cjs

@@ -1,42 +0,0 @@
-/**
- * Generates an in-page table of contents based on headings.
- */
-module.exports = function (doc, options) {
-  options = {
-    levels: ['h2'], // headings to include (they must have an id)
-    container: 'nav', // the container to append links to
-    listItem: true, // if true, links will be wrapped in <li>
-    within: 'body', // the element containing the headings to summarize
-    ...options
-  };
-
-  const container = doc.querySelector(options.container);
-  const within = doc.querySelector(options.within);
-  const headingSelector = options.levels.map(h => `${h}[id]`).join(', ');
-
-  if (!container || !within) {
-    return doc;
-  }
-
-  within.querySelectorAll(headingSelector).forEach(heading => {
-    const listItem = doc.createElement('li');
-    const link = doc.createElement('a');
-    const level = heading.tagName.slice(1);
-
-    link.href = `#${heading.id}`;
-    link.textContent = heading.textContent;
-
-    if (options.listItem) {
-      // List item + link
-      listItem.setAttribute('data-level', level);
-      listItem.append(link);
-      container.append(listItem);
-    } else {
-      // Link only
-      link.setAttribute('data-level', level);
-      container.append(link);
-    }
-  });
-
-  return doc;
-};

docs/_utilities/typography.cjs

@@ -1,23 +0,0 @@
-const smartquotes = require('smartquotes');
-
-smartquotes.replacements.push([/---/g, '\u2014']); // em dash
-smartquotes.replacements.push([/--/g, '\u2013']); // en dash
-smartquotes.replacements.push([/\.\.\./g, '\u2026']); // ellipsis
-smartquotes.replacements.push([/\(c\)/gi, '\u00A9']); // copyright
-smartquotes.replacements.push([/\(r\)/gi, '\u00AE']); // registered trademark
-smartquotes.replacements.push([/\?!/g, '\u2048']); // ?!
-smartquotes.replacements.push([/!!/g, '\u203C']); // !!
-smartquotes.replacements.push([/\?\?/g, '\u2047']); // ??
-smartquotes.replacements.push([/([0-9]\s?)-(\s?[0-9])/g, '$1\u2013$2']); // number ranges use en dash
-
-/**
- * Improves typography by adding smart quotes and similar corrections within the specified element(s).
- *
- * The provided doc should be a document object provided by JSDOM. The same document will be returned with the
- * appropriate DOM manipulations.
- */
-module.exports = function (doc, selector = 'body') {
-  const elements = [...doc.querySelectorAll(selector)];
-  elements.forEach(el => smartquotes.element(el));
-  return doc;
-};

docs/assets/images/awesome.svg

@@ -1,11 +0,0 @@
-<svg width="733" xmlns="http://www.w3.org/2000/svg" height="733">
-  <circle cy="366.5" cx="366.5" r="366.5"/>
-  <circle cy="366.5" cx="366.5" r="336.5" fill="#fede58"/>
-  <path d="M325 665c-121-21-194-115-212-233v-8l-25-1-1-18h481c6 13 10 27 13 41 13 94-38 146-114 193-45 23-93 29-142 26z"/>
-  <path d="M372 647c52-6 98-28 138-62 28-25 46-56 51-87 4-20 1-57-5-70l-423-1c-2 56 39 118 74 157 31 34 72 54 116 63 11 2 38 2 49 0z" fill="#871945"/>
-  <path d="M76 342c-13-26-13-57-9-85 6-27 18-52 35-68 21-20 50-23 77-18 15 4 28 12 39 23 18 17 30 40 36 67 4 20 4 41 0 60l-6 21z"/>
-  <path d="M234 323c5-6 6-40 2-58-3-16-4-16-10-10-14 14-38 14-52 0-15-18-12-41 6-55 3-3 5-5 5-6-1-4-22-8-34-7-42 4-57.6 40-66.2 77-3 17-1 53 4 59H234z" fill="#fff"/>
-  <path d="M378 343c-2-3-6-20-7-29-5-28-1-57 11-83 15-30 41-52 72-60 29-7 57 0 82 15 26 17 45 49 50 82 2 12 2 33 0 45-1 10-5 26-8 30z"/>
-  <path d="M565 324c4-5 5-34 4-50-2-14-6-24-8-24-1 0-3 2-6 5-17 17-47 13-58-9-7-16-4-31 8-43 4-4 7-8 7-9 0 0-4-2-8-3-51-17-105 20-115 80-3 15 0 43 3 53z" fill="#fff"/>
-  <path d="M504 590s-46 40-105 53c-66 15-114-7-114-7s14-76 93-95c76-18 126 49 126 49z" fill="#f9bedd"/>
-</svg>

docs/assets/images/undraw-taken.svg

@@ -1,32 +0,0 @@
-<svg width="673" height="739" viewBox="0 0 673 739" xmlns="http://www.w3.org/2000/svg">
-  <g fill-rule="nonzero" fill="none">
-    <path d="M467 149.805c-46.62-7.44-99.71-11.41-155-11.41-50.6 0-99.35 3.32-142.98 9.58.01-.67.02-1.34.05-2.01C171.475 65.082 237.996.903 318.914 1.398c80.917.494 146.649 65.48 148.066 146.387.01.68.02 1.35.02 2.02Z" fill="#0BA5E9"/>
-    <path d="M337.55 1.342a149.047 149.047 0 0 0-168.93 143.229c-.031.67-.04 1.34-.05 2.01 12.961-1.86 26.384-3.454 40.164-4.784 3.478-71.745 57.64-130.8 128.816-140.455Z" opacity=".1" fill="#FFF"/>
-    <path d="M532.18 161.625a600.121 600.121 0 0 0-65.2-13.84 943.364 943.364 0 0 0-108.74-10.45 1133.608 1133.608 0 0 0-83.01-.34 973.29 973.29 0 0 0-106.16 8.97 624.292 624.292 0 0 0-77.25 15.66C32.61 177.995 0 199.935 0 223.395s32.61 45.4 91.82 61.77c41.64 11.52 92.98 19.37 148.92 22.97 23.09 1.5 46.96 2.26 71.26 2.26 24.38 0 48.33-.77 71.49-2.27 50.91-3.29 98.01-10.1 137.43-20 .21-.06.41-.11.62-.16 2.66-.66 5.28-1.35 7.87-2.04.93-.26 1.85-.51 2.77-.76a.978.978 0 0 1 .16-.05c.88-.24 1.75-.49 2.62-.73 1.74-.5 3.46-.99 5.15-1.5.08-.02.15-.04.22-.06 1.47-.44 2.91-.88 4.34-1.32 1.17-.37 2.33-.73 3.48-1.1.84-.27 1.67-.54 2.49-.81.6-.2 1.19-.39 1.77-.59.79-.26 1.58-.53 2.36-.8.33-.11.66-.22.98-.34.75-.25 1.48-.51 2.21-.77.79-.28 1.58-.57 2.36-.85.65-.23 1.3-.47 1.94-.71.54-.21 1.07-.41 1.61-.61 1.47-.55 2.91-1.12 4.33-1.68.71-.29 1.42-.57 2.12-.86.69-.28 1.39-.57 2.07-.86 1.12-.47 2.22-.94 3.3-1.41.52-.24 1.05-.47 1.56-.69.39-.18.77-.35 1.16-.53.28-.12.56-.25.83-.38 1.01-.46 2.01-.93 2.99-1.4 3.76-1.8 7.27-3.64 10.53-5.52 20.45-11.71 31.24-24.7 31.24-38.2 0-23.46-32.61-45.4-91.82-61.77Zm-.54 121.62c-41.69 11.53-93.17 19.38-149.26 22.95-22.81 1.45-46.39 2.2-70.38 2.2-23.91 0-47.41-.74-70.15-2.19-56.18-3.56-107.74-11.41-149.49-22.96C34.09 267.125 2 245.875 2 223.395c0-1.986.252-3.965.74-5.89 5.1-20.28 36.47-39.26 89.62-53.96a623.806 623.806 0 0 1 76.66-15.57 976.027 976.027 0 0 1 106.8-9c11.92-.39 23.98-.583 36.18-.58 15.41 0 30.65.31 45.63.91a941.367 941.367 0 0 1 109.37 10.5 598.858 598.858 0 0 1 64.64 13.74c53.14 14.7 84.5 33.67 89.61 53.94.496 1.93.75 3.916.75 5.91 0 22.48-32.09 43.73-90.36 59.85Z" fill="#3F3D56"/>
-    <path d="M623.43 224.305c0 13.36-11.01 26-30.67 37.29-3.27 1.88-6.79 3.72-10.53 5.52-.98.47-1.98.94-2.99 1.4-.27.13-.55.26-.83.38-.39.18-.77.35-1.16.53-.51.22-1.04.45-1.56.69-1.08.47-2.18.94-3.3 1.41-.68.29-1.38.58-2.07.86-.7.29-1.41.57-2.12.86-1.42.56-2.86 1.13-4.33 1.68-.54.2-1.07.4-1.61.61-.64.24-1.29.48-1.94.71-.78.28-1.57.57-2.36.85-.73.26-1.46.52-2.21.77-.32.12-.65.23-.98.34-.78.27-1.57.54-2.36.8-.58.2-1.17.39-1.77.59-.82.27-1.65.54-2.49.81-1.15.37-2.31.73-3.48 1.1-1.43.44-2.87.88-4.34 1.32-.07.02-.14.04-.22.06-1.69.51-3.41 1-5.15 1.5-.87.24-1.74.49-2.62.73a.978.978 0 0 0-.16.05c-.92.25-1.84.5-2.77.76-2.58.68-5.21 1.37-7.87 2.04-.21.05-.41.1-.62.16-38.35 9.58-85.4 16.56-137.47 19.93-22.81 1.47-46.59 2.25-71.02 2.25-24.65 0-48.63-.79-71.62-2.29-137.24-8.95-239.38-43.03-239.38-83.71.01-2.475.388-4.936 1.12-7.3.06.17.12.33.19.5 14.27 37.48 115.54 67.77 246.94 75.16 20.13 1.14 40.98 1.73 62.32 1.73 21.43 0 42.36-.6 62.57-1.74 131.29-7.42 232.46-37.72 246.68-75.17.24-.6.45-1.2.63-1.8a25.304 25.304 0 0 1 1.55 8.62ZM91.67 213.54c-16.643 0-34.331-3.58-34.331-10.216 0-6.636 17.688-10.217 34.33-10.217 16.643 0 34.331 3.58 34.331 10.217 0 6.636-17.688 10.217-34.33 10.217Zm0-18.433c-19.054 0-32.331 4.33-32.331 8.217 0 3.886 13.277 8.217 32.33 8.217 19.053 0 32.331-4.33 32.331-8.217 0-3.886-13.278-8.217-32.33-8.217Z" fill="#3F3D56"/>
-    <path d="M162.67 260.54c-16.643 0-34.331-3.58-34.331-10.216 0-6.636 17.688-10.217 34.33-10.217 16.643 0 34.331 3.58 34.331 10.217 0 6.636-17.688 10.217-34.33 10.217Zm0-18.433c-19.054 0-32.331 4.33-32.331 8.217 0 3.886 13.277 8.217 32.33 8.217 19.053 0 32.331-4.33 32.331-8.217 0-3.886-13.278-8.217-32.33-8.217ZM531.67 213.54c-16.643 0-34.331-3.58-34.331-10.216 0-6.636 17.688-10.217 34.33-10.217 16.643 0 34.331 3.58 34.331 10.217 0 6.636-17.688 10.217-34.33 10.217Zm0-18.433c-19.054 0-32.331 4.33-32.331 8.217 0 3.886 13.277 8.217 32.33 8.217 19.053 0 32.331-4.33 32.331-8.217 0-3.886-13.278-8.217-32.33-8.217ZM460.67 260.54c-16.643 0-34.331-3.58-34.331-10.216 0-6.636 17.688-10.217 34.33-10.217 16.643 0 34.331 3.58 34.331 10.217 0 6.636-17.688 10.217-34.33 10.217Zm0-18.433c-19.054 0-32.331 4.33-32.331 8.217 0 3.886 13.277 8.217 32.33 8.217 19.053 0 32.331-4.33 32.331-8.217 0-3.886-13.278-8.217-32.33-8.217ZM311.67 282.54c-16.643 0-34.331-3.58-34.331-10.216 0-6.636 17.688-10.217 34.33-10.217 16.643 0 34.331 3.58 34.331 10.217 0 6.636-17.688 10.217-34.33 10.217Zm0-18.433c-19.054 0-32.331 4.33-32.331 8.217 0 3.886 13.277 8.217 32.33 8.217 19.053 0 32.331-4.33 32.331-8.217 0-3.886-13.278-8.217-32.33-8.217Z" fill="#3F3D56"/>
-    <circle fill="#2F2E41" cx="336.978" cy="450.705" r="42.012"/>
-    <path fill="#2F2E41" d="m300.555 488.547 20.447-10.24 5.715 11.413-20.447 10.24z"/>
-    <ellipse fill="#2F2E41" transform="rotate(-56.601 300.086 492.946)" cx="300.086" cy="492.946" rx="3.989" ry="10.636"/>
-    <path fill="#2F2E41" d="m347.239 489.72 5.715-11.412 20.447 10.24-5.715 11.412z"/>
-    <ellipse fill="#2F2E41" transform="rotate(-33.399 373.87 492.946)" cx="373.87" cy="492.946" rx="10.636" ry="3.989"/>
-    <circle fill="#FFF" cx="334.037" cy="440.429" r="14.359"/>
-    <ellipse fill="#3F3D56" transform="rotate(-45 334.135 434.282)" cx="334.135" cy="434.282" rx="4.766" ry="4.8"/>
-    <path d="M370.12 405c.632-15.553-12.773-28.727-29.941-29.425-17.168-.697-31.597 11.346-32.229 26.9-.632 15.553 11.302 19.087 28.47 19.785 17.167.697 33.068-1.706 33.7-17.26Z" fill="#0BA5E9"/>
-    <ellipse fill="#2F2E41" transform="rotate(-40.645 380.654 456.766)" cx="380.654" cy="456.766" rx="6.594" ry="21.006"/>
-    <ellipse fill="#2F2E41" transform="rotate(-49.355 293.42 456.766)" cx="293.419" cy="456.766" rx="21.006" ry="6.594"/>
-    <path d="M348.517 467.262a9.572 9.572 0 1 1-18.836 3.428l-.003-.018c-.942-5.202 3.08-7.043 8.282-7.985 5.203-.942 9.615-.628 10.557 4.575Z" fill="#FFF"/>
-    <path d="M266 495.395a2 2 0 0 1-2-2v-118a2 2 0 0 1 4 0v118a2 2 0 0 1-2 2ZM236 601.395a2 2 0 0 1-2-2v-86a2 2 0 0 1 4 0v86a2 2 0 0 1-2 2ZM313 530.395a2 2 0 0 1-2-2v-118a2 2 0 0 1 4 0v118a2 2 0 0 1-2 2ZM284 615.395a2 2 0 0 1-2-2v-48a2 2 0 0 1 4 0v48a2 2 0 0 1-2 2ZM325 369.395a2 2 0 0 1-2-2v-48a2 2 0 0 1 4 0v48a2 2 0 0 1-2 2ZM225 390.395a2 2 0 0 1-2-2v-48a2 2 0 0 1 4 0v48a2 2 0 0 1-2 2ZM399 395.395a2 2 0 0 1-2-2v-48a2 2 0 0 1 4 0v48a2 2 0 0 1-2 2ZM395 545.395a2 2 0 0 1-2-2v-58a2 2 0 0 1 4 0v58a2 2 0 0 1-2 2ZM355 596.395a2 2 0 0 1-2-2v-86a2 2 0 0 1 4 0v86a2 2 0 0 1-2 2ZM363 449.395a2 2 0 0 1-2-2v-118a2 2 0 0 1 4 0v118a2 2 0 0 1-2 2Z" fill="#CCC"/>
-    <ellipse fill="#2F2E41" transform="rotate(-39.938 594.37 683.981)" cx="594.369" cy="683.981" rx="6.76" ry="21.534"/>
-    <circle fill="#2F2E41" transform="rotate(-71.565 548.562 676.503)" cx="548.562" cy="676.503" r="43.067"/>
-    <path fill="#2F2E41" d="M553.707 710.303h13.084v23.442h-13.084zM527.54 710.303h13.084v23.442H527.54z"/>
-    <ellipse fill="#2F2E41" cx="555.888" cy="734.017" rx="10.903" ry="4.089"/>
-    <ellipse fill="#2F2E41" cx="529.72" cy="733.472" rx="10.903" ry="4.089"/>
-    <path d="M535.04 622.366c3.845-15.487 20.82-24.6 37.914-20.356 17.094 4.245 27.834 20.24 23.989 35.727-3.846 15.487-16.604 15.537-33.698 11.293-17.094-4.245-32.051-11.177-28.206-26.664Z" fill="#0BA5E9"/>
-    <ellipse fill="#2F2E41" transform="rotate(-64.626 500.054 656.52)" cx="500.054" cy="656.52" rx="6.76" ry="21.534"/>
-    <circle fill="#FFF" cx="542.124" cy="667.416" r="14.359"/>
-    <circle fill="#3F3D56" cx="536.222" cy="662.269" r="4.786"/>
-    <circle fill="#FFF" cx="542" cy="697.395" r="6"/>
-    <path d="M671.531 738.395h-236a1 1 0 1 1 0-2h236a1 1 0 0 1 0 2Z" fill="#3F3D56"/>
-  </g>
-</svg>

docs/assets/plugins/code-block/code-block.css

@@ -1,12 +1,11 @@
-/* Interactive code blocks */
-.code-preview {
+.code-block {
   position: relative;
   border-radius: 3px;
   background-color: var(--sl-color-neutral-50);
   margin-bottom: 1.5rem;
 }
 
-.code-preview__preview {
+.code-block__preview {
   position: relative;
   border: solid 1px var(--sl-color-neutral-200);
   border-bottom: none;
@@ -19,7 +18,7 @@
 }
 
 /* Block the preview while dragging to prevent iframes from intercepting drag events */
-.code-preview__preview--dragging:after {
+.code-block__preview--dragging:after {
   content: '';
   position: absolute;
   top: 0;
@@ -30,7 +29,7 @@
   cursor: ew-resize;
 }
 
-.code-preview__resizer {
+.code-block__resizer {
   display: flex;
   align-items: center;
   justify-content: center;
@@ -45,34 +44,35 @@
   border-left: solid 1px var(--sl-color-neutral-200);
   border-top-right-radius: 3px;
   cursor: ew-resize;
+  transition: 250ms background-color;
 }
 
 @media screen and (max-width: 600px) {
-  .code-preview__preview {
+  .code-block__preview {
     padding-right: 1.5rem;
   }
 
-  .code-preview__resizer {
+  .code-block__resizer {
     display: none;
   }
 }
 
-.code-preview__source {
+.code-block__source {
   border: solid 1px var(--sl-color-neutral-200);
   border-bottom: none;
   border-radius: 0 !important;
   display: none;
 }
 
-.code-preview--expanded .code-preview__source {
+.code-block--expanded .code-block__source {
   display: block;
 }
 
-.code-preview__source pre {
+.code-block__source pre {
   margin: 0;
 }
 
-.code-preview__buttons {
+.code-block__buttons {
   position: relative;
   border: solid 1px var(--sl-color-neutral-200);
   border-bottom-left-radius: 3px;
@@ -80,7 +80,7 @@
   display: flex;
 }
 
-.code-preview__button {
+.code-block__button {
   flex: 0 0 auto;
   height: 2.5rem;
   min-width: 2.5rem;
@@ -96,39 +96,39 @@
   cursor: pointer;
 }
 
-.code-preview__button:not(:last-of-type) {
+.code-block__button:not(:last-of-type) {
   border-right: solid 1px var(--sl-color-neutral-200);
 }
 
-.code-preview__button--html,
-.code-preview__button--react {
+.code-block__button--html,
+.code-block__button--react {
   width: 70px;
   display: flex;
   place-items: center;
   justify-content: center;
 }
 
-.code-preview__button--selected {
+.code-block__button--selected {
   font-weight: 700;
   color: var(--sl-color-primary-600);
 }
 
-.code-preview__button--codepen {
+.code-block__button--codepen {
   display: flex;
   place-items: center;
   width: 6rem;
 }
 
-.code-preview__button:first-of-type {
+.code-block__button:first-of-type {
   border-bottom-left-radius: 3px;
 }
 
-.code-preview__button:last-of-type {
+.code-block__button:last-of-type {
   border-bottom-right-radius: 3px;
 }
 
-.code-preview__button:hover,
-.code-preview__button:active {
+.code-block__button:hover,
+.code-block__button:active {
   box-shadow: 0 0 0 1px var(--sl-color-primary-400);
   border-right-color: transparent;
   background-color: var(--sl-color-primary-50);
@@ -136,13 +136,13 @@
   z-index: 1;
 }
 
-.code-preview__button:focus-visible {
+.code-block__button:focus-visible {
   outline: none;
   outline: var(--sl-focus-ring);
   z-index: 2;
 }
 
-.code-preview__toggle {
+.code-block__toggle {
   position: relative;
   display: flex;
   flex: 1 1 auto;
@@ -151,23 +151,75 @@
   width: 100%;
   color: var(--sl-color-neutral-600);
   cursor: pointer;
+  -webkit-appearance: none;
 }
 
-.code-preview__toggle svg {
+.code-block__toggle svg {
   width: 1em;
   height: 1em;
   margin-left: 0.25rem;
 }
 
-.code-preview--expanded .code-preview__toggle svg {
+.code-block--expanded .code-block__toggle svg {
   transform: rotate(180deg);
 }
 
-/* We can apply data-flavor="html|react" to any element on the page to toggle it when the flavor changes */
-.flavor-html [data-flavor]:not([data-flavor='html']) {
+/* Copy button styles */
+.markdown-section .docsify-copy-code-button {
+  top: 4px;
+  right: 4px;
+  background-color: var(--sl-color-neutral-500);
+  border-radius: var(--sl-border-radius-medium);
+  font-family: var(--sl-font-sans);
+  font-size: var(--sl-font-size-x-small);
+  font-weight: var(--sl-font-weight-semibold);
+  text-transform: uppercase;
+  padding: 8px;
+  user-select: none;
+  transition: 0.1s all;
+}
+
+.markdown-section .docsify-copy-code-button.copied {
+  animation: pulse 0.75s;
+  --pulse-color: var(--sl-color-neutral-600);
+}
+
+@keyframes pulse {
+  0% {
+    box-shadow: 0 0 0 0 var(--pulse-color);
+  }
+  70% {
+    box-shadow: 0 0 0 0.5rem transparent;
+  }
+  100% {
+    box-shadow: 0 0 0 0 transparent;
+  }
+}
+
+.markdown-section .docsify-copy-code-button .label {
+  transition: none;
+}
+
+.markdown-section .docsify-copy-code-button .success,
+.markdown-section .docsify-copy-code-button .error {
   display: none;
 }
 
-.flavor-react [data-flavor]:not([data-flavor='react']) {
+.markdown-section .docsify-copy-code-button:focus-visible {
+  outline: var(--sl-focus-ring);
+  outline-offset: var(--sl-focus-ring-offset);
+}
+
+.markdown-section .docsify-copy-code-button:active {
+  background-color: var(--sl-color-neutral-600);
+  transform: scale(0.92);
+}
+
+/* We can apply data-flavor="html|react" to any element on the page to toggle it when the user's flavor changes */
+body.flavor-html [data-flavor]:not([data-flavor='html']) {
+  display: none;
+}
+
+body.flavor-react [data-flavor]:not([data-flavor='react']) {
   display: none;
 }

docs/assets/plugins/code-block/code-block.js

@@ -0,0 +1,374 @@
+/* global Prism */
+
+(() => {
+  const reactVersion = '17.0.2';
+  let flavor = getFlavor();
+  let count = 1;
+
+  // Sync flavor UI on page load
+  setFlavor(getFlavor());
+
+  if (!window.$docsify) {
+    throw new Error('Docsify must be loaded before installing this plugin.');
+  }
+
+  function convertModuleLinks(html) {
+    const version = sessionStorage.getItem('sl-version');
+
+    html = html
+      .replace(/@shoelace-style\/shoelace/g, `https://cdn.skypack.dev/@shoelace-style/shoelace@${version}`)
+      .replace(/from 'react'/g, `from 'https://cdn.skypack.dev/react@${reactVersion}'`)
+      .replace(/from "react"/g, `from "https://cdn.skypack.dev/react@${reactVersion}"`);
+
+    return html;
+  }
+
+  function getAdjacentExample(name, pre) {
+    let currentPre = pre.nextElementSibling;
+
+    while (currentPre?.tagName.toLowerCase() === 'pre') {
+      if (currentPre?.getAttribute('data-lang').split(' ').includes(name)) {
+        return currentPre;
+      }
+
+      currentPre = currentPre.nextElementSibling;
+    }
+
+    return null;
+  }
+
+  function runScript(script) {
+    const newScript = document.createElement('script');
+
+    if (script.type === 'module') {
+      newScript.type = 'module';
+      newScript.textContent = script.innerHTML;
+    } else {
+      newScript.appendChild(document.createTextNode(`(() => { ${script.innerHTML} })();`));
+    }
+
+    script.parentNode.replaceChild(newScript, script);
+  }
+
+  function getFlavor() {
+    return localStorage.getItem('flavor') || 'html';
+  }
+
+  function setFlavor(newFlavor) {
+    flavor = ['html', 'react'].includes(newFlavor) ? newFlavor : 'html';
+    localStorage.setItem('flavor', flavor);
+
+    // Set the flavor class on the body
+    document.body.classList.toggle('flavor-html', flavor === 'html');
+    document.body.classList.toggle('flavor-react', flavor === 'react');
+  }
+
+  window.$docsify.plugins.push(hook => {
+    // Convert code blocks to previews
+    hook.afterEach((html, next) => {
+      const domParser = new DOMParser();
+      const doc = domParser.parseFromString(html, 'text/html');
+
+      const htmlButton = `
+        <button
+          type="button"
+          title="Show HTML code"
+          class="code-block__button code-block__button--html ${flavor === 'html' ? 'code-block__button--selected' : ''}"
+        >
+          HTML
+        </button>
+      `;
+
+      const reactButton = `
+        <button
+          type="button"
+          title="Show React code"
+          class="code-block__button code-block__button--react ${
+            flavor === 'react' ? 'code-block__button--selected' : ''
+          }"
+        >
+          React
+        </button>
+      `;
+
+      const codePenButton = `
+        <button type="button" class="code-block__button code-block__button--codepen" title="Edit on CodePen">
+          <svg
+            width="138"
+            height="26"
+            viewBox="0 0 138 26"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2.3"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          >
+            <path d="M80 6h-9v14h9 M114 6h-9 v14h9 M111 13h-6 M77 13h-6 M122 20V6l11 14V6 M22 16.7L33 24l11-7.3V9.3L33 2L22 9.3V16.7z M44 16.7L33 9.3l-11 7.4 M22 9.3l11 7.3 l11-7.3 M33 2v7.3 M33 16.7V24 M88 14h6c2.2 0 4-1.8 4-4s-1.8-4-4-4h-6v14 M15 8c-1.3-1.3-3-2-5-2c-4 0-7 3-7 7s3 7 7 7 c2 0 3.7-0.8 5-2 M64 13c0 4-3 7-7 7h-5V6h5C61 6 64 9 64 13z" />
+          </svg>
+        </button>
+      `;
+
+      [...doc.querySelectorAll('code[class^="lang-"]')].forEach(code => {
+        if (code.classList.contains('preview')) {
+          const isExpanded = code.classList.contains('expanded');
+          const pre = code.closest('pre');
+          const sourceGroupId = `code-block-source-group-${count}`;
+          const toggleId = `code-block-toggle-${count}`;
+          const reactPre = getAdjacentExample('react', pre);
+          const hasReact = reactPre !== null;
+
+          pre.setAttribute('data-lang', pre.getAttribute('data-lang').replace(/ preview$/, ''));
+          pre.setAttribute('aria-labelledby', toggleId);
+
+          const codeBlock = `
+            <div class="code-block ${isExpanded ? 'code-block--expanded' : ''}">
+              <div class="code-block__preview">
+                ${code.textContent}
+                <div class="code-block__resizer">
+                  <sl-icon name="grip-vertical"></sl-icon>
+                </div>
+              </div>
+
+              <div class="code-block__source-group" id="${sourceGroupId}">
+                <div class="code-block__source code-block__source--html" ${hasReact ? 'data-flavor="html"' : ''}>
+                  ${pre.outerHTML}
+                </div>
+
+                ${
+                  hasReact
+                    ? `
+                  <div class="code-block__source code-block__source--react" data-flavor="react">
+                    ${reactPre.outerHTML}
+                  </div>
+                `
+                    : ''
+                }
+              </div>
+
+              <div class="code-block__buttons">
+                <button
+                  type="button"
+                  class="code-block__button code-block__toggle"
+                  aria-expanded="${isExpanded ? 'true' : 'false'}"
+                  aria-controls="${sourceGroupId}"
+                >
+                  Source
+                  <svg
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    stroke="currentColor"
+                    stroke-width="2"
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                  >
+                    <polyline points="6 9 12 15 18 9"></polyline>
+                  </svg>
+                </button>
+
+                ${hasReact ? ` ${htmlButton} ${reactButton} ` : ''}
+
+                ${!code.classList.contains('no-codepen') ? codePenButton : ''}
+              </div>
+            </div>
+          `;
+
+          pre.replaceWith(domParser.parseFromString(codeBlock, 'text/html').body);
+          reactPre?.remove();
+
+          count++;
+        }
+      });
+
+      // Force the highlighter to run again so JSX fields get highlighted properly
+      requestAnimationFrame(() => Prism.highlightAll());
+
+      next(doc.body.innerHTML);
+    });
+
+    // After the page is done loading, force scripts in previews to execute
+    hook.doneEach(() => {
+      [...document.querySelectorAll('.code-block__preview script')].map(script => runScript(script));
+    });
+
+    // Horizontal resizing
+    hook.doneEach(() => {
+      [...document.querySelectorAll('.code-block__preview')].forEach(preview => {
+        const resizer = preview.querySelector('.code-block__resizer');
+        let startX;
+        let startWidth;
+
+        function dragStart(event) {
+          startX = event.changedTouches ? event.changedTouches[0].pageX : event.clientX;
+          startWidth = parseInt(document.defaultView.getComputedStyle(preview).width, 10);
+          preview.classList.add('code-block__preview--dragging');
+          event.preventDefault();
+          document.documentElement.addEventListener('mousemove', dragMove);
+          document.documentElement.addEventListener('touchmove', dragMove);
+          document.documentElement.addEventListener('mouseup', dragStop);
+          document.documentElement.addEventListener('touchend', dragStop);
+        }
+
+        function dragMove(event) {
+          setWidth(startWidth + (event.changedTouches ? event.changedTouches[0].pageX : event.pageX) - startX);
+        }
+
+        function dragStop() {
+          preview.classList.remove('code-block__preview--dragging');
+          document.documentElement.removeEventListener('mousemove', dragMove);
+          document.documentElement.removeEventListener('touchmove', dragMove);
+          document.documentElement.removeEventListener('mouseup', dragStop);
+          document.documentElement.removeEventListener('touchend', dragStop);
+        }
+
+        function setWidth(width) {
+          preview.style.width = `${width}px`;
+        }
+
+        resizer.addEventListener('mousedown', dragStart);
+        resizer.addEventListener('touchstart', dragStart, { passive: true });
+      }, false);
+    });
+  });
+
+  // Toggle source mode
+  document.addEventListener('click', event => {
+    const button = event.target.closest('.code-block__button');
+    const codeBlock = button?.closest('.code-block');
+
+    if (button?.classList.contains('code-block__button--html')) {
+      // Show HTML
+      setFlavor('html');
+      toggleSource(codeBlock, true);
+    } else if (button?.classList.contains('code-block__button--react')) {
+      // Show React
+      setFlavor('react');
+      toggleSource(codeBlock, true);
+    } else if (button?.classList.contains('code-block__toggle')) {
+      // Toggle source
+      toggleSource(codeBlock);
+    } else {
+      return;
+    }
+
+    // Update flavor buttons
+    [...document.querySelectorAll('.code-block')].forEach(cb => {
+      cb.querySelector('.code-block__button--html')?.classList.toggle(
+        'code-block__button--selected',
+        flavor === 'html'
+      );
+      cb.querySelector('.code-block__button--react')?.classList.toggle(
+        'code-block__button--selected',
+        flavor === 'react'
+      );
+    });
+  });
+
+  function toggleSource(codeBlock, force) {
+    const toggle = codeBlock.querySelector('.code-block__toggle');
+
+    if (toggle) {
+      codeBlock.classList.toggle('code-block--expanded', force === undefined ? undefined : force);
+      event.target.setAttribute('aria-expanded', codeBlock.classList.contains('code-block--expanded'));
+    }
+  }
+
+  // Show pulse when copying
+  document.addEventListener('click', event => {
+    const button = event.target.closest('.docsify-copy-code-button');
+    if (button) {
+      button.classList.remove('copied');
+      requestAnimationFrame(() => {
+        button.addEventListener('animationend', () => button.classList.remove('copied'), { once: true });
+        button.classList.add('copied');
+      });
+    }
+  });
+
+  // Open in CodePen
+  document.addEventListener('click', event => {
+    const button = event.target.closest('button');
+    const version = sessionStorage.getItem('sl-version');
+
+    if (button?.classList.contains('code-block__button--codepen')) {
+      const codeBlock = button.closest('.code-block');
+      const htmlExample = codeBlock.querySelector('.code-block__source--html > pre > code')?.textContent;
+      const reactExample = codeBlock.querySelector('.code-block__source--react > pre > code')?.textContent;
+      const isReact = flavor === 'react' && typeof reactExample === 'string';
+      const theme = localStorage.getItem('theme');
+      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+      const isDark = theme === 'dark' || (theme === 'auto' && prefersDark);
+      const editors = isReact ? '0010' : '1000';
+      let htmlTemplate = '';
+      let jsTemplate = '';
+      let cssTemplate = '';
+
+      const form = document.createElement('form');
+      form.action = 'https://codepen.io/pen/define';
+      form.method = 'POST';
+      form.target = '_blank';
+
+      // HTML templates
+      if (!isReact) {
+        htmlTemplate =
+          `<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${version}/dist/shoelace.js"></script>\n` +
+          `\n${htmlExample}`;
+        jsTemplate = '';
+      }
+
+      // React templates
+      if (isReact) {
+        htmlTemplate = '<div id="root"></div>';
+        jsTemplate =
+          `import React from 'https://cdn.skypack.dev/react@${reactVersion}';\n` +
+          `import ReactDOM from 'https://cdn.skypack.dev/react-dom@${reactVersion}';\n` +
+          `import { setBasePath } from 'https://cdn.skypack.dev/@shoelace-style/shoelace@${version}/dist/utilities/base-path';\n` +
+          `\n` +
+          `// Set the base path for Shoelace assets\n` +
+          `setBasePath('https://cdn.skypack.dev/@shoelace-style/shoelace@${version}/dist/')\n` +
+          `\n${convertModuleLinks(reactExample)}\n` +
+          `\n` +
+          `ReactDOM.render(<App />, document.getElementById('root'));`;
+      }
+
+      // CSS templates
+      cssTemplate =
+        `@import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${version}/dist/themes/${
+          isDark ? 'dark' : 'light'
+        }.css';\n` +
+        '\n' +
+        'body {\n' +
+        '  font: 16px sans-serif;\n' +
+        '  background-color: var(--sl-color-neutral-0);\n' +
+        '  color: var(--sl-color-neutral-900);\n' +
+        '  padding: 1rem;\n' +
+        '}';
+
+      // Docs: https://blog.codepen.io/documentation/prefill/
+      const data = {
+        title: '',
+        description: '',
+        tags: ['shoelace', 'web components'],
+        editors,
+        head: `<meta name="viewport" content="width=device-width">`,
+        html_classes: `sl-theme-${isDark ? 'dark' : 'light'}`,
+        css_external: ``,
+        js_external: ``,
+        js_module: true,
+        js_pre_processor: isReact ? 'babel' : 'none',
+        html: htmlTemplate,
+        css: cssTemplate,
+        js: jsTemplate
+      };
+
+      const input = document.createElement('input');
+      input.type = 'hidden';
+      input.name = 'data';
+      input.value = JSON.stringify(data);
+      form.append(input);
+
+      document.body.append(form);
+      form.submit();
+      form.remove();
+    }
+  });
+})();

docs/assets/plugins/metadata/metadata.js

@@ -0,0 +1,597 @@
+(() => {
+  const isDev = location.hostname === 'localhost';
+  const isNext = location.hostname === 'next.shoelace.style';
+  const customElements = fetch('/dist/custom-elements.json')
+    .then(res => res.json())
+    .catch(err => console.error(err));
+
+  function createPropsTable(props) {
+    const table = document.createElement('table');
+    table.classList.add('metadata-table');
+    table.innerHTML = `
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Description</th>
+          <th>Reflects</th>
+          <th>Type</th>
+          <th>Default</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${props
+          .map(prop => {
+            const hasAttribute = !!prop.attribute;
+            const isAttributeDifferent = prop.attribute !== prop.name;
+            let attributeInfo = '';
+
+            if (!hasAttribute) {
+              attributeInfo = `<br><small>(property only)</small>`;
+            } else if (isAttributeDifferent) {
+              attributeInfo = `
+                <br>
+                <sl-tooltip content="This attribute is different from its property">
+                  <small>
+                    <code class="nowrap">
+                      ${escapeHtml(prop.attribute)}
+                    </code>
+                  </small>
+                </sl-tooltip>`;
+            }
+
+            return `
+              <tr>
+                <td>
+                  <code class="nowrap">${escapeHtml(prop.name)}</code>
+                  ${attributeInfo}
+                </td>
+                <td>
+                  ${escapeHtml(prop.description)}
+                </td>
+                <td style="text-align: center;">${
+                  prop.reflects ? '<sl-icon label="yes" name="check-lg"></sl-icon>' : ''
+                }</td>
+                <td>${prop.type?.text ? `<code>${escapeHtml(prop.type?.text || '')}</code>` : '-'}</td>
+                <td>${prop.default ? `<code>${escapeHtml(prop.default)}</code>` : '-'}</td>
+              </tr>
+            `;
+          })
+          .join('')}
+
+          <tr>
+            <td class="nowrap"><code>updateComplete</code></td>
+            <td>
+              A read-only promise that resolves when the component has
+              <a href="/getting-started/usage?id=component-rendering-and-updating">finished updating</a>.
+            </td>
+            <td></td>
+            <td></td>
+            <td></td>
+          </tr>
+        </tbody>
+    `;
+
+    return table.outerHTML;
+  }
+
+  function createEventsTable(events) {
+    const table = document.createElement('table');
+    table.classList.add('metadata-table');
+    table.innerHTML = `
+      <thead>
+        <tr>
+          <th data-flavor="html">Name</th>
+          <th data-flavor="react">React Event</th>
+          <th>Description</th>
+          <th>Event Detail</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${events
+          .map(
+            event => `
+              <tr>
+                <td data-flavor="html"><code class="nowrap">${escapeHtml(event.name)}</code></td>
+                <td data-flavor="react"><code class="nowrap">${escapeHtml(event.reactName)}</code></td>
+                <td>${escapeHtml(event.description)}</td>
+                <td>${event.type?.text ? `<code>${escapeHtml(event.type?.text)}` : '-'}</td>
+              </tr>
+            `
+          )
+          .join('')}
+      </tbody>
+    `;
+
+    return table.outerHTML;
+  }
+
+  function createMethodsTable(methods) {
+    const table = document.createElement('table');
+    table.classList.add('metadata-table');
+    table.innerHTML = `
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Description</th>
+          <th>Arguments</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${methods
+          .map(
+            method => `
+              <tr>
+                <td class="nowrap"><code>${escapeHtml(method.name)}()</code></td>
+                <td>${escapeHtml(method.description)}</td>
+                <td>
+                  ${
+                    method.parameters?.length
+                      ? `
+                        <code>${escapeHtml(
+                          method.parameters.map(param => `${param.name}: ${param.type?.text || ''}`).join(', ')
+                        )}</code>
+                      `
+                      : '-'
+                  }
+                </td>
+              </tr>
+           `
+          )
+          .join('')}
+      </tbody>
+    `;
+
+    return table.outerHTML;
+  }
+
+  function createSlotsTable(slots) {
+    const table = document.createElement('table');
+    table.classList.add('metadata-table');
+    table.innerHTML = `
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${slots
+          .map(
+            slot => `
+              <tr>
+                <td class="nowrap">${slot.name ? `<code>${escapeHtml(slot.name)}</code>` : '(default)'}</td>
+                <td>${escapeHtml(slot.description)}</td>
+              </tr>
+            `
+          )
+          .join('')}
+      </tbody>
+    `;
+
+    return table.outerHTML;
+  }
+
+  function createCustomPropertiesTable(styles) {
+    const table = document.createElement('table');
+    table.classList.add('metadata-table');
+    table.innerHTML = `
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Description</th>
+          <th>Default</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${styles
+          .map(
+            style => `
+              <tr>
+                <td class="nowrap"><code>${escapeHtml(style.name)}</code></td>
+                <td>${escapeHtml(style.description)}</td>
+                <td>${style.default ? `<code>${escapeHtml(style.default)}</code>` : ''}</td>
+              </tr>
+            `
+          )
+          .join('')}
+      </tbody>
+    `;
+
+    return table.outerHTML;
+  }
+
+  function createPartsTable(parts) {
+    const table = document.createElement('table');
+    table.classList.add('metadata-table');
+    table.innerHTML = `
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${parts
+          .map(
+            part => `
+              <tr>
+                <td class="nowrap"><code>${escapeHtml(part.name)}</code></td>
+                <td>${escapeHtml(part.description)}</td>
+              </tr>
+           `
+          )
+          .join('')}
+      </tbody>
+    `;
+
+    return table.outerHTML;
+  }
+
+  function createAnimationsTable(animations) {
+    const table = document.createElement('table');
+    table.classList.add('metadata-table');
+    table.innerHTML = `
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${animations
+          .map(
+            animation => `
+              <tr>
+                <td class="nowrap"><code>${escapeHtml(animation.name)}</code></td>
+                <td>${escapeHtml(animation.description)}</td>
+              </tr>
+            `
+          )
+          .join('')}
+      </tbody>
+    `;
+
+    return table.outerHTML;
+  }
+
+  function createDependenciesList(targetComponent, allComponents) {
+    const ul = document.createElement('ul');
+    const dependencies = [];
+
+    // Recursively fetch sub-dependencies
+    function getDependencies(tag) {
+      const component = allComponents.find(c => c.tagName === tag);
+      if (!component || !Array.isArray(component.dependencies)) {
+        return;
+      }
+
+      component.dependencies?.forEach(dependentTag => {
+        if (!dependencies.includes(dependentTag)) {
+          dependencies.push(dependentTag);
+        }
+        getDependencies(dependentTag);
+      });
+    }
+
+    getDependencies(targetComponent);
+    dependencies.sort().forEach(tag => {
+      const li = document.createElement('li');
+      li.innerHTML = `<code>&lt;${tag}&gt;</code>`;
+      ul.appendChild(li);
+    });
+
+    return ul.outerHTML;
+  }
+
+  function escapeHtml(html) {
+    if (!html) {
+      return '';
+    }
+    return html
+      .toString()
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;')
+      .replace(/\[(.*?)\]\((.*?)\)/g, '<a href="$2" rel="noopener noreferrer" target="_blank">$1</a>')
+      .replace(/`(.*?)`/g, '<code>$1</code>');
+  }
+
+  function getAllComponents(metadata) {
+    const allComponents = [];
+    metadata.modules?.forEach(module => {
+      module.declarations?.forEach(declaration => {
+        if (declaration.customElement) {
+          // Generate the dist path based on the src path and attach it to the component
+          declaration.path = module.path.replace(/^src\//, 'dist/').replace(/\.ts$/, '.js');
+
+          allComponents.push(declaration);
+        }
+      });
+    });
+
+    return allComponents;
+  }
+
+  function getComponent(metadata, tagName) {
+    return getAllComponents(metadata).find(component => component.tagName === tagName);
+  }
+
+  if (!window.$docsify) {
+    throw new Error('Docsify must be loaded before installing this plugin.');
+  }
+
+  window.$docsify.plugins.push(hook => {
+    hook.mounted(async () => {
+      const metadata = await customElements;
+      const target = document.querySelector('.app-name');
+
+      // Add version
+      const version = document.createElement('div');
+      version.classList.add('sidebar-version');
+      version.textContent = isDev ? 'Development' : isNext ? 'Next' : metadata.package.version;
+      target.appendChild(version);
+
+      // Store version for reuse
+      sessionStorage.setItem('sl-version', metadata.package.version);
+
+      // Add repo buttons
+      const buttons = document.createElement('div');
+      buttons.classList.add('sidebar-buttons');
+      buttons.innerHTML = `
+        <sl-button size="small" class="repo-button repo-button--sponsor" href="https://github.com/sponsors/claviska" target="_blank">
+          <sl-icon slot="prefix" name="heart"></sl-icon> Sponsor
+        </sl-button>
+        <sl-button size="small" class="repo-button repo-button--github" href="https://github.com/shoelace-style/shoelace/stargazers" target="_blank">
+          <sl-icon slot="prefix" name="github"></sl-icon> Star
+        </sl-button>
+        <sl-button size="small" class="repo-button repo-button--twitter" href="https://twitter.com/shoelace_style" target="_blank">
+          <sl-icon slot="prefix" name="twitter"></sl-icon> Follow
+        </sl-button>
+      `;
+      target.appendChild(buttons);
+    });
+
+    hook.beforeEach(async (content, next) => {
+      const metadata = await customElements;
+
+      // Replace %VERSION% placeholders
+      content = content.replace(/%VERSION%/g, metadata.package.version);
+
+      // Handle [component-header] tags
+      content = content.replace(/\[component-header:([a-z-]+)\]/g, (match, tag) => {
+        const component = getComponent(metadata, tag);
+        let result = '';
+
+        if (!component) {
+          console.error(`Component not found in metadata: ${tag}`);
+          return next(content);
+        }
+
+        let badgeType = 'neutral';
+        if (component.status === 'stable') {
+          badgeType = 'primary';
+        }
+        if (component.status === 'experimental') {
+          badgeType = 'warning';
+        }
+        if (component.status === 'planned') {
+          badgeType = 'neutral';
+        }
+        if (component.status === 'deprecated') {
+          badgeType = 'danger';
+        }
+
+        result += `
+          <div class="component-header">
+            <div class="component-header__tag">
+              <code>&lt;${component.tagName}&gt; | ${component.title ?? component.name}</code>
+            </div>
+
+            <div class="component-header__info">
+              <sl-badge variant="neutral" pill>
+                Since ${component.since || '?'}
+              </sl-badge>
+
+              <sl-badge variant="${badgeType}" pill style="text-transform: capitalize;">
+                ${component.status}
+              </sl-badge>
+            </div>
+
+            <div class="component-header__summary">
+              ${component.summary ? `<p>${marked(component.summary)}</p>` : ''}
+            </div>
+          </div>
+        `;
+
+        return result.replace(/^ +| +$/gm, '');
+      });
+
+      // Handle [component-metadata] tags
+      content = content.replace(/\[component-metadata:([a-z-]+)\]/g, (match, tag) => {
+        const component = getComponent(metadata, tag);
+        let result = '';
+
+        if (!component) {
+          console.error(`Component not found in metadata: ${tag}`);
+          return next(content);
+        }
+
+        // Remove members that are private or don't have a description
+        const members = component.members?.filter(member => member.description && member.privacy !== 'private');
+        const methods = members?.filter(prop => prop.kind === 'method' && prop.privacy !== 'private');
+        const props = members?.filter(prop => {
+          // Look for a corresponding attribute
+          const attribute = component.attributes?.find(attr => attr.fieldName === prop.name);
+          if (attribute) {
+            prop.attribute = attribute.name || attribute.fieldName;
+          }
+
+          return prop.kind === 'field' && prop.privacy !== 'private';
+        });
+
+        if (component.path) {
+          /* prettier-ignore */
+          result += `
+            ## Importing
+
+            If you're using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to
+            use any of the following snippets to [cherry pick](getting-started/installation#cherry-picking) this component.
+
+            <sl-tab-group>
+            <sl-tab slot="nav" panel="script">Script</sl-tab>
+            <sl-tab slot="nav" panel="import">Import</sl-tab>
+            <sl-tab slot="nav" panel="bundler">Bundler</sl-tab>
+            <sl-tab slot="nav" panel="react">React</sl-tab>
+
+            <sl-tab-panel name="script">\n
+            To import this component from [the CDN](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace) using a script tag:
+
+            \`\`\`html
+            <script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${metadata.package.version}/dist/${component.path}"></script>
+            \`\`\`
+            </sl-tab-panel>
+
+            <sl-tab-panel name="import">\n
+            To import this component from [the CDN](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace) using a JavaScript import:
+
+            \`\`\`js
+            import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${metadata.package.version}/dist/${component.path}';
+            \`\`\`
+            </sl-tab-panel>
+
+            <sl-tab-panel name="bundler">\n
+            To import this component using [a bundler](/getting-started/installation#bundling):
+            \`\`\`js
+            import '@shoelace-style/shoelace/dist/${component.path}';
+            \`\`\`
+            </sl-tab-panel>
+
+            <sl-tab-panel name="react">\n
+            To import this component as a [React component](/frameworks/react):
+            \`\`\`js
+            import { ${component.name} } from '@shoelace-style/shoelace/dist/react';
+            \`\`\`
+            </sl-tab-panel>
+            </sl-tab-group>
+
+            <div class="sponsor-callout">
+              <p>
+                Shoelace is designed, developed, and maintained by <a href="https://twitter.com/claviska" target="_blank">Cory LaViska</a>.
+                Please sponsor my open source work on GitHub. Your support will keep this project alive and growing!
+              </p>
+
+              <p>
+                <sl-button class="repo-button repo-button--sponsor" href="https://github.com/sponsors/claviska" target="_blank">
+                  <sl-icon slot="prefix" name="heart"></sl-icon> Sponsor <span class="sponsor-callout__secondary-label">Development</span>
+                </sl-button>
+
+                <sl-button class="repo-button repo-button--github" href="https://github.com/shoelace-style/shoelace/stargazers" target="_blank">
+                  <sl-icon slot="prefix" name="github"></sl-icon> Star <span class="sponsor-callout__secondary-label">on GitHub</span>
+                </sl-button>
+
+                <sl-button class="repo-button repo-button--twitter" href="https://twitter.com/shoelace_style" target="_blank">
+                  <sl-icon slot="prefix" name="twitter"></sl-icon> Follow <span class="sponsor-callout__secondary-label">on Twitter</span>
+                </sl-button>
+              </p>
+            </div>
+          `;
+        }
+
+        if (component.slots?.length) {
+          result += `
+            ## Slots
+            ${createSlotsTable(component.slots)}
+
+            _Learn more about [using slots](/getting-started/usage#slots)._
+          `;
+        }
+
+        if (props?.length) {
+          result += `
+            ## Attributes & Properties
+            ${createPropsTable(props)}
+
+            _Learn more about [attributes and properties](/getting-started/usage#properties)._
+          `;
+        }
+
+        if (component.events?.length) {
+          result += `
+            ## Events
+            ${createEventsTable(component.events)}
+
+            _Learn more about [listening to events](/getting-started/usage#events)._
+          `;
+        }
+
+        if (methods?.length) {
+          result += `
+            ## Methods
+
+            ${createMethodsTable(methods)}
+
+            _Learn more about [calling methods](/getting-started/usage#methods)._
+          `;
+        }
+
+        if (component.cssProperties?.length) {
+          result += `
+            ## CSS Custom Properties
+            ${createCustomPropertiesTable(component.cssProperties)}
+
+            _Learn more about [customizing CSS Custom Properties](/getting-started/customizing#custom-properties)._
+          `;
+        }
+
+        if (component.cssParts?.length) {
+          result += `
+            ## CSS Parts
+            ${createPartsTable(component.cssParts)}
+
+            _Learn more about [customizing CSS Parts](/getting-started/customizing#component-parts)._
+          `;
+        }
+
+        if (component.animations?.length) {
+          result += `
+            ## Animations
+            ${createAnimationsTable(component.animations)}
+
+            _Learn more about [customizing animations](/getting-started/customizing#animations)._
+          `;
+        }
+
+        if (component.dependencies?.length) {
+          result += `
+            ## Dependencies
+
+            This component automatically imports the following dependencies.
+
+            ${createDependenciesList(component.tagName, getAllComponents(metadata))}
+          `;
+        }
+
+        // Strip whitespace so markdown doesn't process things as code blocks
+        return result.replace(/^ +| +$/gm, '');
+      });
+
+      next(content);
+    });
+
+    // Wrap tables so we can scroll them horizontally when needed
+    hook.doneEach(() => {
+      const content = document.querySelector('.content');
+      const tables = [...content.querySelectorAll('table')];
+
+      tables.forEach(table => {
+        table.outerHTML = `
+          <div class="table-wrapper">
+            ${table.outerHTML}
+          </div>
+        `;
+      });
+    });
+  });
+})();

docs/assets/plugins/scroll-position/scroll-position.js

@@ -0,0 +1,24 @@
+(() => {
+  if (!window.$docsify) {
+    throw new Error('Docsify must be loaded before installing this plugin.');
+  }
+
+  //
+  // Docsify generates pages dynamically and asynchronously, so when a reload happens, the scroll position can't be
+  // be restored immediately. This plugin waits until Docsify loads the page and then restores it.
+  //
+  window.$docsify.plugins.push(hook => {
+    hook.ready(() => {
+      // Restore
+      const scrollTop = sessionStorage.getItem('bs-scroll');
+      if (scrollTop) {
+        document.documentElement.scrollTop = scrollTop;
+      }
+
+      // Remember
+      document.addEventListener('scroll', () => {
+        sessionStorage.setItem('bs-scroll', document.documentElement.scrollTop);
+      });
+    });
+  });
+})();

docs/assets/plugins/search/search.css

@@ -0,0 +1,192 @@
+body.site-search-visible {
+  overflow: hidden;
+}
+
+.sidebar .search-box {
+  margin: 1.25rem 26px;
+}
+
+.sidebar .search-box kbd {
+  margin-top: 2px;
+  margin-right: 1rem;
+}
+
+/* Site search */
+.site-search {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 1000;
+}
+
+.site-search[hidden] {
+  display: none;
+}
+
+.site-search__overlay {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: var(--sl-overlay-background-color);
+  z-index: -1;
+}
+
+.site-search__panel {
+  display: flex;
+  flex-direction: column;
+  max-width: 460px;
+  max-height: calc(100vh - 20rem);
+  background-color: var(--sl-panel-background-color);
+  border-radius: var(--sl-border-radius-large);
+  box-shadow: var(--sl-shadow-x-large);
+  margin: 10rem auto;
+}
+
+@media screen and (max-width: 900px) {
+  .site-search__panel {
+    max-width: 100%;
+    max-height: calc(92vh - 120px); /* allow iOS browser chrome */
+    margin: 4vh var(--sl-spacing-medium);
+  }
+}
+
+.site-search__input::part(base) {
+  border: none;
+  background: transparent;
+  border-radius: var(--sl-border-radius-large);
+}
+
+.site-search__input:focus-within::part(base) {
+  outline: none;
+  box-shadow: none;
+}
+
+.site-search__input {
+  --sl-input-height-large: 4rem;
+}
+
+.site-search__body {
+  flex: 1 1 auto;
+  overflow: auto;
+}
+
+.site-search--has-results .site-search__body {
+  border-top: solid 1px var(--sl-color-neutral-200);
+}
+
+.site-search__results {
+  display: none;
+  line-height: var(--sl-line-height-dense);
+  list-style: none;
+  padding: var(--sl-spacing-x-small) 0;
+  margin: 0;
+}
+
+.site-search--has-results .site-search__results {
+  display: block;
+}
+
+.site-search__results a {
+  display: block;
+  text-decoration: none;
+  padding: var(--sl-spacing-x-small) var(--sl-spacing-large);
+}
+
+.site-search__results li a:hover,
+.site-search__results li a:hover small {
+  background-color: var(--sl-color-neutral-100);
+}
+
+.site-search__results li[aria-selected='true'] a,
+.site-search__results li[aria-selected='true'] a small,
+.site-search__results li[aria-selected='true'] a sl-icon {
+  outline: none;
+  color: var(--sl-color-neutral-0);
+  background-color: var(--sl-color-primary-600);
+}
+
+.sl-theme-dark .site-search__results li[aria-selected='true'] a,
+.sl-theme-dark .site-search__results li[aria-selected='true'] a small,
+.sl-theme-dark .site-search__results li[aria-selected='true'] a sl-icon {
+  background-color: var(--sl-color-primary-400);
+  color: var(--sl-color-neutral-1000);
+}
+
+.site-search__results h3 {
+  font-weight: var(--sl-font-weight-semibold);
+  margin: 0;
+}
+
+.site-search__results small {
+  display: block;
+  color: var(--sl-color-neutral-600);
+}
+
+.site-search__result {
+  padding: 0;
+  margin: 0;
+}
+
+.site-search__result a {
+  display: flex;
+  align-items: center;
+  gap: var(--sl-spacing-medium);
+}
+
+.site-search__result-icon {
+  flex: 0 0 auto;
+  display: flex;
+  color: var(--sl-color-neutral-400);
+  font-size: var(--sl-font-size-x-large);
+}
+
+.site-search__result-description {
+  flex: 1 1 auto;
+}
+
+.site-search__empty {
+  display: none;
+  border-top: solid 1px var(--sl-color-neutral-200);
+  text-align: center;
+  padding: var(--sl-spacing-x-large);
+}
+
+.site-search--no-results .site-search__empty {
+  display: block;
+}
+
+.site-search__footer {
+  display: flex;
+  justify-content: center;
+  gap: var(--sl-spacing-large);
+  border-top: solid 1px var(--sl-color-neutral-200);
+  border-bottom-left-radius: inherit;
+  border-bottom-right-radius: inherit;
+  padding: var(--sl-spacing-medium);
+}
+
+.site-search__footer small {
+  color: var(--sl-color-neutral-700);
+}
+
+@media screen and (max-width: 900px) {
+  .site-search__footer {
+    display: none;
+  }
+}
+
+/* Forced colors mode */
+@media (forced-colors: active) {
+  .site-search__panel {
+    border: solid 1px var(--sl-color-neutral-0);
+  }
+
+  .site-search__results li[aria-selected='true'] a {
+    outline: dashed 1px SelectedItem;
+    outline-offset: -1px;
+  }
+}

docs/assets/plugins/search/search.js

@@ -0,0 +1,320 @@
+/* global lunr */
+(() => {
+  if (!window.$docsify) {
+    throw new Error('Docsify must be loaded before installing this plugin.');
+  }
+
+  window.$docsify.plugins.push(hook => {
+    // Append the search box to the sidebar
+    hook.mounted(() => {
+      const appName = document.querySelector('.sidebar .app-name');
+      const searchBox = document.createElement('div');
+      searchBox.classList.add('search-box');
+      searchBox.innerHTML = `
+        <sl-input type="search" placeholder="Search" pill>
+          <sl-icon slot="prefix" name="search"></sl-icon>
+          <kbd slot="suffix" title="Press / to search">/</kbd>
+        </sl-input>
+      `;
+      const searchBoxInput = searchBox.querySelector('sl-input');
+
+      appName.insertAdjacentElement('afterend', searchBox);
+
+      // Show the search panel when the search is clicked
+      searchBoxInput.addEventListener('mousedown', event => {
+        event.preventDefault();
+        show();
+      });
+
+      // Show the search panel when a key is pressed
+      searchBoxInput.addEventListener('keydown', event => {
+        if (event.key === 'Tab') {
+          return;
+        }
+
+        // Pass the character that was typed through to the search input
+        if (event.key.length === 1) {
+          event.preventDefault();
+          input.value = event.key;
+          show();
+        }
+      });
+    });
+
+    // Append the search panel to the body
+    const siteSearch = document.createElement('div');
+    siteSearch.classList.add('site-search');
+    siteSearch.hidden = true;
+    siteSearch.innerHTML = `
+      <div class="site-search__overlay"></div>
+      <div
+        id="site-search-panel"
+        class="site-search__panel"
+        role="combobox"
+        aria-expanded="false"
+        aria-owns="site-search-results"
+        aria-activedescendant=""
+      >
+        <header class="site-search__header">
+          <sl-input
+            class="site-search__input"
+            type="search"
+            placeholder="Search this site"
+            aria-autocomplete="list"
+            aria-controls="site-search-results"
+            size="large"
+            clearable
+          >
+            <sl-icon slot="prefix" name="search"></sl-icon>
+          </sl-input>
+        </header>
+        <div class="site-search__body">
+          <ul
+            id="site-search-results"
+            class="site-search__results"
+            role="listbox"
+            aria-labelledby="site-search-panel"
+          >
+          </ul>
+          <div class="site-search__empty">No results found.</div>
+        </div>
+        <footer class="site-search__footer">
+          <small><kbd>↑</kbd> <kbd>↓</kbd> navigate</small>
+          <small><kbd>↲</kbd> select</small>
+          <small><kbd>esc</kbd> close</small>
+        </footer>
+      </div>
+    `;
+    document.body.append(siteSearch);
+
+    const overlay = siteSearch.querySelector('.site-search__overlay');
+    const panel = siteSearch.querySelector('.site-search__panel');
+    const input = siteSearch.querySelector('.site-search__input');
+    const results = siteSearch.querySelector('.site-search__results');
+    const animationDuration = 150;
+    const searchDebounce = 200;
+    let isShowing = false;
+    let searchTimeout;
+    let searchIndex;
+    let map;
+
+    // Load search data
+    fetch('../../../search.json')
+      .then(res => res.json())
+      .then(data => {
+        searchIndex = lunr.Index.load(data.searchIndex);
+        map = data.map;
+      });
+
+    async function show() {
+      isShowing = true;
+      document.body.classList.add('site-search-visible');
+      siteSearch.hidden = false;
+      requestAnimationFrame(() => input.focus());
+      updateResults();
+
+      await Promise.all([
+        panel.animate(
+          [
+            { opacity: 0, transform: 'scale(.9)' },
+            { opacity: 1, transform: 'scale(1)' }
+          ],
+          { duration: animationDuration }
+        ).finished,
+        overlay.animate([{ opacity: 0 }, { opacity: 1 }], { duration: animationDuration }).finished
+      ]);
+
+      document.addEventListener('mousedown', handleDocumentMouseDown);
+      document.addEventListener('keydown', handleDocumentKeyDown);
+      document.addEventListener('focusin', handleDocumentFocusIn);
+    }
+
+    async function hide() {
+      isShowing = false;
+      document.body.classList.remove('site-search-visible');
+
+      await Promise.all([
+        panel.animate(
+          [
+            { opacity: 1, transform: 'scale(1)' },
+            { opacity: 0, transform: 'scale(.9)' }
+          ],
+          { duration: animationDuration }
+        ).finished,
+        overlay.animate([{ opacity: 1 }, { opacity: 0 }], { duration: animationDuration }).finished
+      ]);
+
+      siteSearch.hidden = true;
+      input.value = '';
+      updateResults();
+
+      document.removeEventListener('mousedown', handleDocumentMouseDown);
+      document.removeEventListener('keydown', handleDocumentKeyDown);
+      document.removeEventListener('focusin', handleDocumentFocusIn);
+    }
+
+    function handleInput() {
+      // Debounce search queries
+      clearTimeout(searchTimeout);
+      searchTimeout = setTimeout(() => updateResults(input.value), searchDebounce);
+    }
+
+    function handleDocumentFocusIn(event) {
+      // Close when focus leaves the panel
+      if (event.target.closest('.site-search__panel') !== panel) {
+        hide();
+      }
+    }
+
+    function handleDocumentMouseDown(event) {
+      // Close when clicking outside of the panel
+      if (event.target.closest('.site-search__overlay') === overlay) {
+        hide();
+      }
+    }
+
+    function handleDocumentKeyDown(event) {
+      // Close when pressing escape
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        hide();
+        return;
+      }
+
+      // Handle keyboard selections
+      if (['ArrowDown', 'ArrowUp', 'Home', 'End', 'Enter'].includes(event.key)) {
+        event.preventDefault();
+
+        const currentEl = results.querySelector('[aria-selected="true"]');
+        const items = [...results.querySelectorAll('li')];
+        const index = items.indexOf(currentEl);
+        let nextEl;
+
+        if (items.length === 0) {
+          return;
+        }
+
+        switch (event.key) {
+          case 'ArrowUp':
+            nextEl = items[Math.max(0, index - 1)];
+            break;
+          case 'ArrowDown':
+            nextEl = items[Math.min(items.length - 1, index + 1)];
+            break;
+          case 'Home':
+            nextEl = items[0];
+            break;
+          case 'End':
+            nextEl = items[items.length - 1];
+            break;
+          case 'Enter':
+            currentEl?.querySelector('a')?.click();
+            break;
+        }
+
+        // Update the selected item
+        items.forEach(item => {
+          if (item === nextEl) {
+            const a = nextEl.querySelector('a');
+            panel.setAttribute('aria-activedescendant', a.id);
+
+            item.setAttribute('aria-selected', 'true');
+            nextEl.scrollIntoView({ block: 'nearest' });
+          } else {
+            item.setAttribute('aria-selected', 'false');
+          }
+        });
+      }
+    }
+
+    async function updateResults(query = '') {
+      try {
+        await searchIndex;
+
+        const hasQuery = query.length > 0;
+        const searchTokens = query
+          .split(' ')
+          .map((term, index, arr) => `${term}${index === arr.length - 1 ? `* ${term}~1` : '~1'}`)
+          .join(' ');
+        const matches = hasQuery ? searchIndex.search(`${query} ${searchTokens}`) : [];
+        const hasResults = hasQuery && matches.length > 0;
+        siteSearch.classList.toggle('site-search--has-results', hasQuery && hasResults);
+        siteSearch.classList.toggle('site-search--no-results', hasQuery && !hasResults);
+        panel.setAttribute('aria-expanded', hasQuery && hasResults ? 'true' : 'false');
+
+        results.innerHTML = '';
+
+        matches.forEach((match, index) => {
+          const page = map[match.ref];
+          const li = document.createElement('li');
+          const a = document.createElement('a');
+          let icon = 'file-text';
+
+          a.setAttribute('role', 'option');
+          a.setAttribute('id', `search-result-item-${match.ref}`);
+
+          if (page.url.includes('getting-started/')) {
+            icon = 'lightbulb';
+          }
+          if (page.url.includes('resources/')) {
+            icon = 'book';
+          }
+          if (page.url.includes('components/')) {
+            icon = 'puzzle';
+          }
+          if (page.url.includes('tokens/')) {
+            icon = 'palette2';
+          }
+          if (page.url.includes('utilities/')) {
+            icon = 'wrench';
+          }
+          if (page.url.includes('tutorials/')) {
+            icon = 'joystick';
+          }
+
+          a.href = window.$docsify.routerMode === 'hash' ? `/#/${page.url}` : `/${page.url}`;
+          a.innerHTML = `
+            <div class="site-search__result-icon">
+              <sl-icon name="${icon}" aria-hidden="true"></sl-icon>
+            </div>
+            <div class="site-search__result__details">
+              <h3>${page.title}</h3>
+              <small>${page.url}</small>
+            </div>
+          `;
+
+          li.classList.add('site-search__result');
+          li.setAttribute('aria-selected', index === 0 ? 'true' : 'false');
+          li.appendChild(a);
+          results.appendChild(li);
+        });
+      } catch {
+        // Ignore query errors as the user types
+      }
+    }
+
+    // Show the search panel slash is pressed outside of a form element
+    document.addEventListener('keydown', event => {
+      const isSlash = event.key === '/';
+      const isCtrlK = (event.metaKey || event.ctrlKey) && event.key === 'k';
+
+      if (
+        !isShowing &&
+        (isSlash || isCtrlK) &&
+        !event.composedPath().some(el => ['input', 'textarea'].includes(el?.tagName?.toLowerCase()))
+      ) {
+        event.preventDefault();
+        show();
+      }
+    });
+
+    input.addEventListener('sl-input', handleInput);
+
+    // Close when a result is selected
+    results.addEventListener('click', event => {
+      if (event.target.closest('a')) {
+        hide();
+      }
+    });
+  });
+})();

docs/assets/plugins/theme-picker/theme-picker.css

@@ -0,0 +1,29 @@
+.theme-picker {
+  position: fixed;
+  top: 1rem;
+  right: 1rem;
+  z-index: 30;
+}
+
+.theme-picker:not(:defined) {
+  display: none;
+}
+
+.theme-picker sl-menu-label {
+  white-space: nowrap;
+}
+
+.theme-picker sl-menu-label kbd {
+  margin-left: 0.5rem;
+}
+
+@media screen and (max-width: 768px) {
+  .theme-picker {
+    top: 0.5rem;
+    right: 0.5rem;
+  }
+
+  .theme-picker sl-menu-label {
+    display: none;
+  }
+}

docs/assets/plugins/theme-picker/theme-picker.js

@@ -0,0 +1,82 @@
+(() => {
+  if (!window.$docsify) {
+    throw new Error('Docsify must be loaded before installing this plugin.');
+  }
+
+  window.$docsify.plugins.push(hook => {
+    hook.mounted(() => {
+      function getTheme() {
+        return localStorage.getItem('theme') || 'auto';
+      }
+
+      function isDark() {
+        if (theme === 'auto') {
+          return window.matchMedia('(prefers-color-scheme: dark)').matches;
+        }
+        return theme === 'dark';
+      }
+
+      function setTheme(newTheme) {
+        const noTransitions = Object.assign(document.createElement('style'), {
+          textContent: '* { transition: none !important; }'
+        });
+
+        theme = newTheme;
+        localStorage.setItem('theme', theme);
+
+        // Update the UI
+        [...menu.querySelectorAll('sl-menu-item')].map(item => (item.checked = item.getAttribute('value') === theme));
+        menuIcon.name = isDark() ? 'moon' : 'sun';
+
+        // Toggle the dark mode class without transitions
+        document.body.appendChild(noTransitions);
+        requestAnimationFrame(() => {
+          document.documentElement.classList.toggle('sl-theme-dark', isDark());
+          requestAnimationFrame(() => document.body.removeChild(noTransitions));
+        });
+      }
+
+      let theme = getTheme();
+
+      // Generate the theme picker dropdown
+      const dropdown = document.createElement('sl-dropdown');
+      dropdown.classList.add('theme-picker');
+      dropdown.innerHTML = `
+        <sl-button size="small" pill slot="trigger" caret>
+          <sl-icon name="sun" label="Select Theme"></sl-icon>
+        </sl-button>
+        <sl-menu>
+          <sl-menu-label>Toggle <kbd>\\</kbd></sl-menu-label>
+          <sl-menu-item type="checkbox" value="light">Light</sl-menu-item>
+          <sl-menu-item type="checkbox" value="dark">Dark</sl-menu-item>
+          <sl-divider></sl-divider>
+          <sl-menu-item type="checkbox" value="auto">Auto</sl-menu-item>
+        </sl-menu>
+      `;
+      document.querySelector('.sidebar-toggle').insertAdjacentElement('afterend', dropdown);
+
+      // Listen for selections
+      const menu = dropdown.querySelector('sl-menu');
+      const menuIcon = dropdown.querySelector('sl-icon');
+      menu.addEventListener('sl-select', event => setTheme(event.detail.item.value));
+
+      // Update the theme when the preference changes
+      window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => setTheme(theme));
+
+      // Toggle themes when pressing backslash
+      document.addEventListener('keydown', event => {
+        if (
+          event.key === '\\' &&
+          !event.composedPath().some(el => ['input', 'textarea'].includes(el?.tagName?.toLowerCase()))
+        ) {
+          event.preventDefault();
+
+          setTheme(isDark() ? 'light' : 'dark');
+        }
+      });
+
+      // Set the initial theme and sync the UI
+      setTheme(theme);
+    });
+  });
+})();

docs/assets/scripts/code-previews.js

@@ -1,249 +0,0 @@
-(() => {
-  function convertModuleLinks(html) {
-    html = html
-      .replace(/@shoelace-style\/shoelace/g, `https://esm.sh/@shoelace-style/shoelace@${shoelaceVersion}`)
-      .replace(/from 'react'/g, `from 'https://esm.sh/react@${reactVersion}'`)
-      .replace(/from "react"/g, `from "https://esm.sh/react@${reactVersion}"`);
-
-    return html;
-  }
-
-  function getAdjacentExample(name, pre) {
-    let currentPre = pre.nextElementSibling;
-
-    while (currentPre?.tagName.toLowerCase() === 'pre') {
-      if (currentPre?.getAttribute('data-lang').split(' ').includes(name)) {
-        return currentPre;
-      }
-
-      currentPre = currentPre.nextElementSibling;
-    }
-
-    return null;
-  }
-
-  function runScript(script) {
-    const newScript = document.createElement('script');
-
-    if (script.type === 'module') {
-      newScript.type = 'module';
-      newScript.textContent = script.innerHTML;
-    } else {
-      newScript.appendChild(document.createTextNode(`(() => { ${script.innerHTML} })();`));
-    }
-
-    script.parentNode.replaceChild(newScript, script);
-  }
-
-  function getFlavor() {
-    return sessionStorage.getItem('flavor') || 'html';
-  }
-
-  function setFlavor(newFlavor) {
-    flavor = ['html', 'react'].includes(newFlavor) ? newFlavor : 'html';
-    sessionStorage.setItem('flavor', flavor);
-
-    // Set the flavor class on the body
-    document.documentElement.classList.toggle('flavor-html', flavor === 'html');
-    document.documentElement.classList.toggle('flavor-react', flavor === 'react');
-  }
-
-  function syncFlavor() {
-    setFlavor(getFlavor());
-
-    document.querySelectorAll('.code-preview__button--html').forEach(preview => {
-      if (flavor === 'html') {
-        preview.classList.add('code-preview__button--selected');
-      }
-    });
-
-    document.querySelectorAll('.code-preview__button--react').forEach(preview => {
-      if (flavor === 'react') {
-        preview.classList.add('code-preview__button--selected');
-      }
-    });
-  }
-
-  const shoelaceVersion = document.documentElement.getAttribute('data-shoelace-version');
-  const reactVersion = '18.2.0';
-  const cdndir = 'cdn';
-  const npmdir = 'dist';
-  let flavor = getFlavor();
-  let count = 1;
-
-  // We need the version to open
-  if (!shoelaceVersion) {
-    throw new Error('The data-shoelace-version attribute is missing from <html>.');
-  }
-
-  // Sync flavor UI on page load
-  syncFlavor();
-
-  //
-  // Resizing previews
-  //
-  document.addEventListener('mousedown', handleResizerDrag);
-  document.addEventListener('touchstart', handleResizerDrag, { passive: true });
-
-  function handleResizerDrag(event) {
-    const resizer = event.target.closest('.code-preview__resizer');
-    const preview = event.target.closest('.code-preview__preview');
-
-    if (!resizer || !preview) return;
-
-    let startX = event.changedTouches ? event.changedTouches[0].pageX : event.clientX;
-    let startWidth = parseInt(document.defaultView.getComputedStyle(preview).width, 10);
-
-    event.preventDefault();
-    preview.classList.add('code-preview__preview--dragging');
-    document.documentElement.addEventListener('mousemove', dragMove);
-    document.documentElement.addEventListener('touchmove', dragMove);
-    document.documentElement.addEventListener('mouseup', dragStop);
-    document.documentElement.addEventListener('touchend', dragStop);
-
-    function dragMove(event) {
-      const width = startWidth + (event.changedTouches ? event.changedTouches[0].pageX : event.pageX) - startX;
-      preview.style.width = `${width}px`;
-    }
-
-    function dragStop() {
-      preview.classList.remove('code-preview__preview--dragging');
-      document.documentElement.removeEventListener('mousemove', dragMove);
-      document.documentElement.removeEventListener('touchmove', dragMove);
-      document.documentElement.removeEventListener('mouseup', dragStop);
-      document.documentElement.removeEventListener('touchend', dragStop);
-    }
-  }
-
-  //
-  // Toggle source mode
-  //
-  document.addEventListener('click', event => {
-    const button = event.target.closest('.code-preview__button');
-    const codeBlock = button?.closest('.code-preview');
-
-    if (button?.classList.contains('code-preview__button--html')) {
-      // Show HTML
-      setFlavor('html');
-      toggleSource(codeBlock, true);
-    } else if (button?.classList.contains('code-preview__button--react')) {
-      // Show React
-      setFlavor('react');
-      toggleSource(codeBlock, true);
-    } else if (button?.classList.contains('code-preview__toggle')) {
-      // Toggle source
-      toggleSource(codeBlock);
-    } else {
-      return;
-    }
-
-    // Update flavor buttons
-    [...document.querySelectorAll('.code-preview')].forEach(cb => {
-      cb.querySelector('.code-preview__button--html')?.classList.toggle(
-        'code-preview__button--selected',
-        flavor === 'html'
-      );
-      cb.querySelector('.code-preview__button--react')?.classList.toggle(
-        'code-preview__button--selected',
-        flavor === 'react'
-      );
-    });
-  });
-
-  function toggleSource(codeBlock, force) {
-    codeBlock.classList.toggle('code-preview--expanded', force);
-    event.target.setAttribute('aria-expanded', codeBlock.classList.contains('code-preview--expanded'));
-  }
-
-  //
-  // Open in CodePen
-  //
-  document.addEventListener('click', event => {
-    const button = event.target.closest('button');
-
-    if (button?.classList.contains('code-preview__button--codepen')) {
-      const codeBlock = button.closest('.code-preview');
-      const htmlExample = codeBlock.querySelector('.code-preview__source--html > pre > code')?.textContent;
-      const reactExample = codeBlock.querySelector('.code-preview__source--react > pre > code')?.textContent;
-      const isReact = flavor === 'react' && typeof reactExample === 'string';
-      const theme = document.documentElement.classList.contains('sl-theme-dark') ? 'dark' : 'light';
-      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-      const isDark = theme === 'dark' || (theme === 'auto' && prefersDark);
-      const editors = isReact ? '0010' : '1000';
-      let htmlTemplate = '';
-      let jsTemplate = '';
-      let cssTemplate = '';
-
-      const form = document.createElement('form');
-      form.action = 'https://codepen.io/pen/define';
-      form.method = 'POST';
-      form.target = '_blank';
-
-      // HTML templates
-      if (!isReact) {
-        htmlTemplate =
-          `<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${shoelaceVersion}/${cdndir}/shoelace.js"></script>\n` +
-          `\n${htmlExample}`;
-        jsTemplate = '';
-      }
-
-      // React templates
-      if (isReact) {
-        htmlTemplate = '<div id="root"></div>';
-        jsTemplate =
-          `import React from 'https://esm.sh/react@${reactVersion}';\n` +
-          `import ReactDOM from 'https://esm.sh/react-dom@${reactVersion}';\n` +
-          `import { setBasePath } from 'https://esm.sh/@shoelace-style/shoelace@${shoelaceVersion}/${cdndir}/utilities/base-path';\n` +
-          `\n` +
-          `// Set the base path for Shoelace assets\n` +
-          `setBasePath('https://esm.sh/@shoelace-style/shoelace@${shoelaceVersion}/${npmdir}/')\n` +
-          `\n${convertModuleLinks(reactExample)}\n` +
-          `\n` +
-          `ReactDOM.render(<App />, document.getElementById('root'));`;
-      }
-
-      // CSS templates
-      cssTemplate =
-        `@import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${shoelaceVersion}/${cdndir}/themes/${
-          isDark ? 'dark' : 'light'
-        }.css';\n` +
-        '\n' +
-        'body {\n' +
-        '  font: 16px sans-serif;\n' +
-        '  background-color: var(--sl-color-neutral-0);\n' +
-        '  color: var(--sl-color-neutral-900);\n' +
-        '  padding: 1rem;\n' +
-        '}';
-
-      // Docs: https://blog.codepen.io/documentation/prefill/
-      const data = {
-        title: '',
-        description: '',
-        tags: ['shoelace', 'web components'],
-        editors,
-        head: `<meta name="viewport" content="width=device-width">`,
-        html_classes: `sl-theme-${isDark ? 'dark' : 'light'}`,
-        css_external: ``,
-        js_external: ``,
-        js_module: true,
-        js_pre_processor: isReact ? 'babel' : 'none',
-        html: htmlTemplate,
-        css: cssTemplate,
-        js: jsTemplate
-      };
-
-      const input = document.createElement('input');
-      input.type = 'hidden';
-      input.name = 'data';
-      input.value = JSON.stringify(data);
-      form.append(input);
-
-      document.documentElement.append(form);
-      form.submit();
-      form.remove();
-    }
-  });
-
-  // Set the initial flavor
-  window.addEventListener('turbo:load', syncFlavor);
-})();

docs/assets/scripts/docs.js

@@ -1,272 +0,0 @@
-//
-// Sidebar
-//
-// When the sidebar is hidden, we apply the inert attribute to prevent focus from reaching it. Due to the many states
-// the sidebar can have (e.g. static, hidden, expanded), we test for visibility by checking to see if it's placed
-// offscreen or not. Then, on resize/transition we make sure to update the attribute accordingly.
-//
-(() => {
-  function getSidebar() {
-    return document.getElementById('sidebar');
-  }
-
-  function isSidebarOpen() {
-    return document.documentElement.classList.contains('sidebar-open');
-  }
-
-  function isSidebarVisible() {
-    return getSidebar().getBoundingClientRect().x >= 0;
-  }
-
-  function toggleSidebar(force) {
-    const isOpen = typeof force === 'boolean' ? force : !isSidebarOpen();
-    return document.documentElement.classList.toggle('sidebar-open', isOpen);
-  }
-
-  function updateInert() {
-    getSidebar().inert = !isSidebarVisible();
-  }
-
-  // Toggle the menu
-  document.addEventListener('click', event => {
-    const menuToggle = event.target.closest('#menu-toggle');
-    if (!menuToggle) return;
-    toggleSidebar();
-  });
-
-  // Update the sidebar's inert state when the window resizes and when the sidebar transitions
-  window.addEventListener('resize', () => toggleSidebar(false));
-
-  document.addEventListener('transitionend', event => {
-    const sidebar = event.target.closest('#sidebar');
-    if (!sidebar) return;
-    updateInert();
-  });
-
-  // Close when a menu item is selected on mobile
-  document.addEventListener('click', event => {
-    const sidebar = event.target.closest('#sidebar');
-    const link = event.target.closest('a');
-    if (!sidebar || !link) return;
-
-    if (isSidebarOpen()) {
-      toggleSidebar();
-    }
-  });
-
-  // Close when open and escape is pressed
-  document.addEventListener('keydown', event => {
-    if (event.key === 'Escape' && isSidebarOpen()) {
-      event.stopImmediatePropagation();
-      toggleSidebar();
-    }
-  });
-
-  // Close when clicking outside of the sidebar
-  document.addEventListener('mousedown', event => {
-    if (isSidebarOpen() & !event.target?.closest('#sidebar, #menu-toggle')) {
-      event.stopImmediatePropagation();
-      toggleSidebar();
-    }
-  });
-
-  updateInert();
-})();
-
-//
-// Theme selector
-//
-(() => {
-  function getTheme() {
-    return localStorage.getItem('theme') || 'auto';
-  }
-
-  function isDark() {
-    if (theme === 'auto') {
-      return window.matchMedia('(prefers-color-scheme: dark)').matches;
-    }
-    return theme === 'dark';
-  }
-
-  function setTheme(newTheme) {
-    theme = newTheme;
-    localStorage.setItem('theme', theme);
-
-    // Update the UI
-    updateSelection();
-
-    // Toggle the dark mode class
-    document.documentElement.classList.toggle('sl-theme-dark', isDark());
-  }
-
-  function updateSelection() {
-    const menu = document.querySelector('#theme-selector sl-menu');
-    if (!menu) return;
-    [...menu.querySelectorAll('sl-menu-item')].map(item => (item.checked = item.getAttribute('value') === theme));
-  }
-
-  let theme = getTheme();
-
-  // Selection is not preserved when changing page, so update when opening dropdown
-  document.addEventListener('sl-show', event => {
-    const themeSelector = event.target.closest('#theme-selector');
-    if (!themeSelector) return;
-    updateSelection();
-  });
-
-  // Listen for selections
-  document.addEventListener('sl-select', event => {
-    const menu = event.target.closest('#theme-selector sl-menu');
-    if (!menu) return;
-    setTheme(event.detail.item.value);
-  });
-
-  // Update the theme when the preference changes
-  window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => setTheme(theme));
-
-  // Toggle with backslash
-  document.addEventListener('keydown', event => {
-    if (
-      event.key === '\\' &&
-      !event.composedPath().some(el => ['input', 'textarea'].includes(el?.tagName?.toLowerCase()))
-    ) {
-      event.preventDefault();
-      setTheme(isDark() ? 'light' : 'dark');
-    }
-  });
-
-  // Set the initial theme and sync the UI
-  setTheme(theme);
-})();
-
-//
-// Open details when printing
-//
-(() => {
-  const detailsOpenOnPrint = new Set();
-
-  window.addEventListener('beforeprint', () => {
-    detailsOpenOnPrint.clear();
-    document.querySelectorAll('details').forEach(details => {
-      if (details.open) {
-        detailsOpenOnPrint.add(details);
-      }
-      details.open = true;
-    });
-  });
-
-  window.addEventListener('afterprint', () => {
-    document.querySelectorAll('details').forEach(details => {
-      details.open = detailsOpenOnPrint.has(details);
-    });
-    detailsOpenOnPrint.clear();
-  });
-})();
-
-//
-// Smooth links
-//
-(() => {
-  document.addEventListener('click', event => {
-    const link = event.target.closest('a');
-    const id = (link?.hash ?? '').substr(1);
-    const isFragment = link?.hasAttribute('href') && link?.getAttribute('href').startsWith('#');
-
-    if (!link || !isFragment || link.getAttribute('data-smooth-link') === 'false') {
-      return;
-    }
-
-    // Scroll to the top
-    if (link.hash === '') {
-      event.preventDefault();
-      window.scroll({ top: 0, behavior: 'smooth' });
-      history.pushState(undefined, undefined, location.pathname);
-    }
-
-    // Scroll to an id
-    if (id) {
-      const target = document.getElementById(id);
-
-      if (target) {
-        event.preventDefault();
-        window.scroll({ top: target.offsetTop, behavior: 'smooth' });
-        history.pushState(undefined, undefined, `#${id}`);
-      }
-    }
-  });
-})();
-
-//
-// Table of Contents scrollspy
-//
-(() => {
-  // This will be stale if its not a function.
-  const getLinks = () => [...document.querySelectorAll('.content__toc a')];
-  const linkTargets = new WeakMap();
-  const visibleTargets = new WeakSet();
-  const observer = new IntersectionObserver(handleIntersect, { rootMargin: '0px 0px' });
-  let debounce;
-
-  function handleIntersect(entries) {
-    entries.forEach(entry => {
-      // Remember which targets are visible
-      if (entry.isIntersecting) {
-        visibleTargets.add(entry.target);
-      } else {
-        visibleTargets.delete(entry.target);
-      }
-    });
-
-    updateActiveLinks();
-  }
-
-  function updateActiveLinks() {
-    const links = getLinks();
-    // Find the first visible target and activate the respective link
-    links.find(link => {
-      const target = linkTargets.get(link);
-
-      if (target && visibleTargets.has(target)) {
-        links.forEach(el => el.classList.toggle('active', el === link));
-        return true;
-      }
-
-      return false;
-    });
-  }
-
-  // Observe link targets
-  function observeLinks() {
-    getLinks().forEach(link => {
-      const hash = link.hash.slice(1);
-      const target = hash ? document.querySelector(`.content__body #${hash}`) : null;
-
-      if (target) {
-        linkTargets.set(link, target);
-        observer.observe(target);
-      }
-    });
-  }
-
-  observeLinks();
-
-  document.addEventListener('turbo:load', updateActiveLinks);
-  document.addEventListener('turbo:load', observeLinks);
-})();
-
-//
-// Show custom versions in the sidebar
-//
-(() => {
-  function updateVersion() {
-    const el = document.querySelector('.sidebar-version');
-    if (!el) return;
-
-    if (location.hostname === 'next.shoelace.style') el.textContent = 'Next';
-    if (location.hostname === 'localhost') el.textContent = 'Development';
-  }
-
-  updateVersion();
-
-  document.addEventListener('turbo:load', updateVersion);
-})();

docs/assets/scripts/search.js

@@ -1,376 +0,0 @@
-(() => {
-  // Append the search dialog to the body
-  const siteSearch = document.createElement('div');
-  const scrollbarWidth = Math.abs(window.innerWidth - document.documentElement.clientWidth);
-
-  siteSearch.classList.add('search');
-  siteSearch.innerHTML = `
-    <div class="search__overlay"></div>
-    <dialog id="search-dialog" class="search__dialog">
-      <div class="search__content">
-        <div class="search__header">
-          <div id="search-combobox" class="search__input-wrapper">
-            <sl-icon name="search"></sl-icon>
-            <input
-              id="search-input"
-              class="search__input"
-              type="search"
-              placeholder="Search"
-              autocomplete="off"
-              autocorrect="off"
-              autocapitalize="off"
-              enterkeyhint="go"
-              spellcheck="false"
-              maxlength="100"
-              role="combobox"
-              aria-autocomplete="list"
-              aria-expanded="true"
-              aria-controls="search-listbox"
-              aria-haspopup="listbox"
-              aria-activedescendant
-            >
-            <button type="button" class="search__clear-button" aria-label="Clear entry" tabindex="-1" hidden>
-              <sl-icon name="x-circle-fill"></sl-icon>
-            </button>
-          </div>
-        </div>
-        <div class="search__body">
-          <ul
-            id="search-listbox"
-            class="search__results"
-            role="listbox"
-            aria-label="Search results"
-          ></ul>
-          <div class="search__empty">No matching pages</div>
-        </div>
-        <footer class="search__footer">
-          <small><kbd>↑</kbd> <kbd>↓</kbd> Navigate</small>
-          <small><kbd>↲</kbd> Select</small>
-          <small><kbd>Esc</kbd> Close</small>
-        </footer>
-      </div>
-    </dialog>
-  `;
-
-  const overlay = siteSearch.querySelector('.search__overlay');
-  const dialog = siteSearch.querySelector('.search__dialog');
-  const input = siteSearch.querySelector('.search__input');
-  const clearButton = siteSearch.querySelector('.search__clear-button');
-  const results = siteSearch.querySelector('.search__results');
-  const version = document.documentElement.getAttribute('data-shoelace-version');
-  const key = `search_${version}`;
-  const searchDebounce = 50;
-  const animationDuration = 150;
-  let isShowing = false;
-  let searchTimeout;
-  let searchIndex;
-  let map;
-
-  const loadSearchIndex = new Promise(resolve => {
-    const cache = localStorage.getItem(key);
-    const wait = 'requestIdleCallback' in window ? requestIdleCallback : requestAnimationFrame;
-
-    // Cleanup older search indices (everything before this version)
-    try {
-      const items = { ...localStorage };
-
-      Object.keys(items).forEach(k => {
-        if (key > k) {
-          localStorage.removeItem(k);
-        }
-      });
-    } catch {
-      /* do nothing */
-    }
-
-    // Look for a cached index
-    try {
-      if (cache) {
-        const data = JSON.parse(cache);
-
-        searchIndex = window.lunr.Index.load(data.searchIndex);
-        map = data.map;
-
-        return resolve();
-      }
-    } catch {
-      /* do nothing */
-    }
-
-    // Wait until idle to fetch the index
-    wait(() => {
-      fetch('/assets/search.json')
-        .then(res => res.json())
-        .then(data => {
-          if (!window.lunr) {
-            console.error('The Lunr search client has not yet been loaded.');
-          }
-
-          searchIndex = window.lunr.Index.load(data.searchIndex);
-          map = data.map;
-
-          // Cache the search index for this version
-          if (version) {
-            try {
-              localStorage.setItem(key, JSON.stringify(data));
-            } catch (err) {
-              console.warn(`Unable to cache the search index: ${err}`);
-            }
-          }
-
-          resolve();
-        });
-    });
-  });
-
-  async function show() {
-    isShowing = true;
-    document.body.append(siteSearch);
-    document.body.classList.add('search-visible');
-    document.body.style.setProperty('--docs-search-scroll-lock-size', `${scrollbarWidth}px`);
-    clearButton.hidden = true;
-    requestAnimationFrame(() => input.focus());
-    updateResults();
-
-    dialog.showModal();
-
-    await Promise.all([
-      dialog.animate(
-        [
-          { opacity: 0, transform: 'scale(.9)', transformOrigin: 'top' },
-          { opacity: 1, transform: 'scale(1)', transformOrigin: 'top' }
-        ],
-        { duration: animationDuration }
-      ).finished,
-      overlay.animate([{ opacity: 0 }, { opacity: 1 }], { duration: animationDuration }).finished
-    ]);
-
-    dialog.addEventListener('mousedown', handleMouseDown);
-    dialog.addEventListener('keydown', handleKeyDown);
-  }
-
-  async function hide() {
-    isShowing = false;
-
-    await Promise.all([
-      dialog.animate(
-        [
-          { opacity: 1, transform: 'scale(1)', transformOrigin: 'top' },
-          { opacity: 0, transform: 'scale(.9)', transformOrigin: 'top' }
-        ],
-        { duration: animationDuration }
-      ).finished,
-      overlay.animate([{ opacity: 1 }, { opacity: 0 }], { duration: animationDuration }).finished
-    ]);
-
-    dialog.close();
-
-    input.blur(); // otherwise Safari will scroll to the bottom of the page on close
-    input.value = '';
-    document.body.classList.remove('search-visible');
-    document.body.style.removeProperty('--docs-search-scroll-lock-size');
-    siteSearch.remove();
-    updateResults();
-
-    dialog.removeEventListener('mousedown', handleMouseDown);
-    dialog.removeEventListener('keydown', handleKeyDown);
-  }
-
-  function handleInput() {
-    clearButton.hidden = input.value === '';
-
-    // Debounce search queries
-    clearTimeout(searchTimeout);
-    searchTimeout = setTimeout(() => updateResults(input.value), searchDebounce);
-  }
-
-  function handleClear() {
-    clearButton.hidden = true;
-    input.value = '';
-    input.focus();
-    updateResults();
-  }
-
-  function handleMouseDown(event) {
-    if (!event.target.closest('.search__content')) {
-      hide();
-    }
-  }
-
-  function handleKeyDown(event) {
-    // Close when pressing escape
-    if (event.key === 'Escape') {
-      event.preventDefault(); // prevent <dialog> from closing immediately so it can animate
-      event.stopImmediatePropagation();
-      hide();
-      return;
-    }
-
-    // Handle keyboard selections
-    if (['ArrowDown', 'ArrowUp', 'Home', 'End', 'Enter'].includes(event.key)) {
-      event.preventDefault();
-
-      const currentEl = results.querySelector('[data-selected="true"]');
-      const items = [...results.querySelectorAll('li')];
-      const index = items.indexOf(currentEl);
-      let nextEl;
-
-      if (items.length === 0) {
-        return;
-      }
-
-      switch (event.key) {
-        case 'ArrowUp':
-          nextEl = items[Math.max(0, index - 1)];
-          break;
-        case 'ArrowDown':
-          nextEl = items[Math.min(items.length - 1, index + 1)];
-          break;
-        case 'Home':
-          nextEl = items[0];
-          break;
-        case 'End':
-          nextEl = items[items.length - 1];
-          break;
-        case 'Enter':
-          currentEl?.querySelector('a')?.click();
-          break;
-      }
-
-      // Update the selected item
-      items.forEach(item => {
-        if (item === nextEl) {
-          input.setAttribute('aria-activedescendant', item.id);
-          item.setAttribute('data-selected', 'true');
-          nextEl.scrollIntoView({ block: 'nearest' });
-        } else {
-          item.setAttribute('data-selected', 'false');
-        }
-      });
-    }
-  }
-
-  async function updateResults(query = '') {
-    try {
-      await loadSearchIndex;
-
-      const hasQuery = query.length > 0;
-      const searchTerms = query
-        .split(' ')
-        .map((term, index, arr) => {
-          // Search API: https://lunrjs.com/guides/searching.html
-          if (index === arr.length - 1) {
-            // The last term is not mandatory and 1x fuzzy. We also duplicate it with a wildcard to match partial words
-            // as the user types.
-            return `${term}~1 ${term}*`;
-          } else {
-            // All other terms are mandatory and 1x fuzzy
-            return `+${term}~1`;
-          }
-        })
-        .join(' ');
-      const matches = hasQuery ? searchIndex.search(searchTerms) : [];
-      const hasResults = hasQuery && matches.length > 0;
-
-      siteSearch.classList.toggle('search--has-results', hasQuery && hasResults);
-      siteSearch.classList.toggle('search--no-results', hasQuery && !hasResults);
-
-      input.setAttribute('aria-activedescendant', '');
-      results.innerHTML = '';
-
-      matches.forEach((match, index) => {
-        const page = map[match.ref];
-        const li = document.createElement('li');
-        const a = document.createElement('a');
-        const displayTitle = page.title ?? '';
-        const displayDescription = page.description ?? '';
-        const displayUrl = page.url.replace(/^\//, '').replace(/\/$/, '');
-        let icon = 'file-text';
-
-        a.setAttribute('role', 'option');
-        a.setAttribute('id', `search-result-item-${match.ref}`);
-
-        if (page.url.includes('getting-started/')) {
-          icon = 'lightbulb';
-        }
-        if (page.url.includes('resources/')) {
-          icon = 'book';
-        }
-        if (page.url.includes('components/')) {
-          icon = 'puzzle';
-        }
-        if (page.url.includes('tokens/')) {
-          icon = 'palette2';
-        }
-        if (page.url.includes('utilities/')) {
-          icon = 'wrench';
-        }
-        if (page.url.includes('tutorials/')) {
-          icon = 'joystick';
-        }
-
-        li.classList.add('search__result');
-        li.setAttribute('role', 'option');
-        li.setAttribute('id', `search-result-item-${match.ref}`);
-        li.setAttribute('data-selected', index === 0 ? 'true' : 'false');
-
-        a.href = page.url;
-        a.innerHTML = `
-          <div class="search__result-icon" aria-hidden="true">
-            <sl-icon name="${icon}"></sl-icon>
-          </div>
-          <div class="search__result__details">
-            <div class="search__result-title"></div>
-            <div class="search__result-description"></div>
-            <div class="search__result-url"></div>
-          </div>
-        `;
-        a.querySelector('.search__result-title').textContent = displayTitle;
-        a.querySelector('.search__result-description').textContent = displayDescription;
-        a.querySelector('.search__result-url').textContent = displayUrl;
-
-        li.appendChild(a);
-        results.appendChild(li);
-      });
-    } catch {
-      // Ignore query errors as the user types
-    }
-  }
-
-  // Show the search dialog when clicking on data-plugin="search"
-  document.addEventListener('click', event => {
-    const searchButton = event.target.closest('[data-plugin="search"]');
-    if (searchButton) {
-      show();
-    }
-  });
-
-  // Show the search dialog when slash (or CMD+K) is pressed and focus is not inside a form element
-  document.addEventListener('keydown', event => {
-    if (
-      !isShowing &&
-      (event.key === '/' || (event.key === 'k' && (event.metaKey || event.ctrlKey))) &&
-      !event.composedPath().some(el => ['input', 'textarea'].includes(el?.tagName?.toLowerCase()))
-    ) {
-      event.preventDefault();
-      show();
-    }
-  });
-
-  // Purge cache when we press CMD+CTRL+R
-  document.addEventListener('keydown', event => {
-    if ((event.metaKey || event.ctrlKey) && event.shiftKey && event.key === 'r') {
-      localStorage.clear();
-    }
-  });
-
-  input.addEventListener('input', handleInput);
-  clearButton.addEventListener('click', handleClear);
-
-  // Close when a result is selected
-  results.addEventListener('click', event => {
-    if (event.target.closest('a')) {
-      hide();
-    }
-  });
-})();

docs/assets/scripts/turbo.js

@@ -1,29 +0,0 @@
-import * as Turbo from 'https://cdn.jsdelivr.net/npm/@hotwired/turbo@7.3.0/+esm';
-
-(() => {
-  if (!window.scrollPositions) {
-    window.scrollPositions = {};
-  }
-
-  function preserveScroll() {
-    document.querySelectorAll('[data-preserve-scroll').forEach(element => {
-      scrollPositions[element.id] = element.scrollTop;
-    });
-  }
-
-  function restoreScroll(event) {
-    document.querySelectorAll('[data-preserve-scroll').forEach(element => {
-      element.scrollTop = scrollPositions[element.id];
-    });
-
-    if (event.detail && event.detail.newBody) {
-      event.detail.newBody.querySelectorAll('[data-preserve-scroll').forEach(element => {
-        element.scrollTop = scrollPositions[element.id];
-      });
-    }
-  }
-
-  window.addEventListener('turbo:before-cache', preserveScroll);
-  window.addEventListener('turbo:before-render', restoreScroll);
-  window.addEventListener('turbo:render', restoreScroll);
-})();

docs/assets/styles/search.css

@@ -1,347 +0,0 @@
-/* Search plugin */
-:root,
-:root.sl-theme-dark {
-  --docs-search-box-background: var(--sl-color-neutral-0);
-  --docs-search-box-border-width: 1px;
-  --docs-search-box-border-color: var(--sl-color-neutral-300);
-  --docs-search-box-color: var(--sl-color-neutral-600);
-  --docs-search-dialog-background: var(--sl-color-neutral-0);
-  --docs-search-border-width: var(--docs-border-width);
-  --docs-search-border-color: var(--docs-border-color);
-  --docs-search-text-color: var(--sl-color-neutral-900);
-  --docs-search-text-color-muted: var(--sl-color-neutral-500);
-  --docs-search-font-weight-normal: var(--sl-font-weight-normal);
-  --docs-search-font-weight-semibold: var(--sl-font-weight-semibold);
-  --docs-search-border-radius: calc(2 * var(--docs-border-radius));
-  --docs-search-accent-color: var(--sl-color-primary-600);
-  --docs-search-icon-color: var(--sl-color-neutral-500);
-  --docs-search-icon-color-active: var(--sl-color-neutral-600);
-  --docs-search-shadow: var(--docs-shadow-x-large);
-  --docs-search-result-background-hover: var(--sl-color-neutral-100);
-  --docs-search-result-color-hover: var(--sl-color-neutral-900);
-  --docs-search-result-background-active: var(--sl-color-primary-600);
-  --docs-search-result-color-active: var(--sl-color-neutral-0);
-  --docs-search-focus-ring: var(--sl-focus-ring);
-  --docs-search-overlay-background: rgb(0 0 0 / 0.33);
-}
-
-:root.sl-theme-dark {
-  --docs-search-overlay-background: rgb(71 71 71 / 0.33);
-}
-
-body.search-visible {
-  padding-right: var(--docs-search-scroll-lock-size) !important;
-  overflow: hidden !important;
-}
-
-/* Search box */
-.search-box {
-  flex: 1 1 auto;
-  display: flex;
-  align-items: center;
-  width: 100%;
-  border: none;
-  border-radius: 9999px;
-  background: var(--docs-search-box-background);
-  border: solid var(--docs-search-box-border-width) var(--docs-search-box-border-color);
-  font: inherit;
-  color: var(--docs-search-box-color);
-  padding: 0.75rem 1rem;
-  margin: var(--sl-spacing-large) 0;
-  cursor: pointer;
-}
-
-.search-box span {
-  flex: 1 1 auto;
-  width: 1rem;
-  height: 1rem;
-  text-align: left;
-  line-height: 1;
-  margin: 0 0.75rem;
-}
-
-.search-box:focus {
-  outline: none;
-}
-
-.search-box:focus-visible {
-  outline: var(--docs-search-focus-ring);
-}
-
-/* Site search */
-.search {
-  position: fixed;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  z-index: 9999;
-}
-
-.search[hidden] {
-  display: none;
-}
-
-.search__overlay {
-  position: absolute;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background: var(--docs-search-overlay-background);
-  z-index: -1;
-}
-
-.search__dialog {
-  width: 100%;
-  height: 100%;
-  max-width: none;
-  max-height: none;
-  background: transparent;
-  border: none;
-  padding: 0;
-  margin: 0;
-}
-
-.search__dialog:focus {
-  outline: none;
-}
-
-.search__dialog::backdrop {
-  display: none;
-}
-
-/* Fixes an iOS Safari 16.4 bug that draws the parent element's border radius incorrectly when showing/hiding results */
-.search__header {
-  background-color: var(--docs-search-dialog-background);
-  border-radius: var(--docs-search-border-radius);
-}
-
-.search--has-results .search__header {
-  border-top-left-radius: var(--docs-search-border-radius);
-  border-top-right-radius: var(--docs-search-border-radius);
-  border-bottom-left-radius: 0;
-  border-bottom-right-radius: 0;
-}
-
-.search__content {
-  display: flex;
-  flex-direction: column;
-  width: 100%;
-  max-width: 500px;
-  max-height: calc(100vh - 20rem);
-  background-color: var(--docs-search-dialog-background);
-  border-radius: var(--docs-search-border-radius);
-  box-shadow: var(--docs-search-shadow);
-  padding: 0;
-  margin: 10rem auto;
-}
-
-@media screen and (max-width: 900px) {
-  .search__content {
-    max-width: calc(100% - 2rem);
-    max-height: calc(90svh);
-    margin: 4vh 1rem;
-  }
-}
-
-.search__input-wrapper {
-  display: flex;
-  align-items: center;
-}
-
-.search__input-wrapper sl-icon {
-  width: 1.5rem;
-  height: 1.5rem;
-  flex: 0 0 auto;
-  color: var(--docs-search-icon-color);
-  margin: 0 1.5rem;
-}
-
-.search__clear-button {
-  display: flex;
-  background: none;
-  border: none;
-  font: inherit;
-  padding: 0;
-  margin: 0;
-  cursor: pointer;
-}
-
-.search__clear-button[hidden] {
-  display: none;
-}
-
-.search__clear-button:active sl-icon {
-  color: var(--docs-search-icon-color-active);
-}
-
-.search__input {
-  flex: 1 1 auto;
-  min-width: 0;
-  border: none;
-  font: inherit;
-  font-size: 1.5rem;
-  font-weight: var(--docs-search-font-weight-normal);
-  color: var(--docs-search-text-color);
-  background: transparent;
-  padding: 1rem 0;
-  margin: 0;
-}
-
-.search__input::placeholder {
-  color: var(--docs-search-text-color-muted);
-}
-
-.search__input::-webkit-search-decoration,
-.search__input::-webkit-search-cancel-button,
-.search__input::-webkit-search-results-button,
-.search__input::-webkit-search-results-decoration {
-  display: none;
-}
-
-.search__input:focus,
-.search__input:focus-visible {
-  outline: none;
-}
-
-.search__body {
-  flex: 1 1 auto;
-  overflow: auto;
-}
-
-.search--has-results .search__body {
-  border-top: solid var(--docs-search-border-width) var(--docs-search-border-color);
-}
-
-.search__results {
-  display: none;
-  line-height: 1.2;
-  list-style: none;
-  padding: 0.5rem 0;
-  margin: 0;
-}
-
-.search--has-results .search__results {
-  display: block;
-}
-
-.search__results a {
-  display: block;
-  text-decoration: none;
-  padding: 0.5rem 1.5rem;
-}
-
-.search__results a:focus-visible {
-  outline: var(--docs-search-focus-ring);
-}
-
-.search__results li a:hover,
-.search__results li a:hover small {
-  background-color: var(--docs-search-result-background-hover);
-  color: var(--docs-search-result-color-hover);
-}
-
-.search__results li[data-selected='true'] a,
-.search__results li[data-selected='true'] a * {
-  outline: none;
-  background-color: var(--docs-search-result-background-active);
-  color: var(--docs-search-result-color-active);
-}
-
-.search__results h3 {
-  font-weight: var(--docs-search-font-weight-semibold);
-  margin: 0;
-}
-
-.search__results small {
-  display: block;
-  color: var(--docs-search-text-color-muted);
-}
-
-.search__result {
-  padding: 0;
-  margin: 0;
-}
-
-.search__result a {
-  display: flex;
-  align-items: center;
-  gap: 1rem;
-}
-
-.search__result-icon {
-  flex: 0 0 auto;
-  display: flex;
-  color: var(--docs-search-text-color-muted);
-}
-
-.search__result-icon sl-icon {
-  font-size: 1.5rem;
-}
-
-.search__result__details {
-  width: calc(100% - 3rem);
-}
-
-.search__result-title,
-.search__result-description,
-.search__result-url {
-  max-width: 400px;
-  line-height: 1.3;
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-}
-
-.search__result-title {
-  font-size: 1.2rem;
-  font-weight: var(--docs-search-font-weight-semibold);
-  color: var(--docs-search-accent-color);
-}
-
-.search__result-description {
-  font-size: 0.875rem;
-  color: var(--docs-search-text-color);
-}
-
-.search__result-url {
-  font-size: 0.875rem;
-  color: var(--docs-search-text-color-muted);
-}
-
-.search__empty {
-  display: none;
-  border-top: solid var(--docs-search-border-width) var(--docs-search-border-color);
-  text-align: center;
-  color: var(--docs-search-text-color-muted);
-  padding: 2rem;
-}
-
-.search--no-results .search__empty {
-  display: block;
-}
-
-.search__footer {
-  display: flex;
-  justify-content: center;
-  gap: 2rem;
-  border-top: solid var(--docs-search-border-width) var(--docs-search-border-color);
-  border-bottom-left-radius: inherit;
-  border-bottom-right-radius: inherit;
-  padding: 1rem;
-}
-
-.search__footer small {
-  color: var(--docs-search-text-color-muted);
-}
-
-.search__footer small kbd:last-of-type {
-  margin-right: 0.25rem;
-}
-
-@media screen and (max-width: 900px) {
-  .search__footer {
-    display: none;
-  }
-}

docs/components/alert.md

@@ -1,20 +1,16 @@
----
-meta:
-  title: Alert
-  description: Alerts are used to display important messages inline or as toast notifications.
-layout: component
----
+# Alert
 
-```html:preview
+[component-header:sl-alert]
+
+```html preview
 <sl-alert open>
   <sl-icon slot="icon" name="info-circle"></sl-icon>
   This is a standard alert. You can customize its content and even the icon.
 </sl-alert>
 ```
 
-```jsx:react
-import SlAlert from '@shoelace-style/shoelace/dist/react/alert';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlAlert, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlAlert open>
@@ -24,9 +20,7 @@ const App = () => (
 );
 ```
 
-:::tip
-Alerts will not be visible if the `open` attribute is not present.
-:::
+?> Alerts will not be visible if the `open` attribute is not present.
 
 ## Examples
 
@@ -34,7 +28,7 @@ Alerts will not be visible if the `open` attribute is not present.
 
 Set the `variant` attribute to change the alert's variant.
 
-```html:preview
+```html preview
 <sl-alert variant="primary" open>
   <sl-icon slot="icon" name="info-circle"></sl-icon>
   <strong>This is super informative</strong><br />
@@ -74,9 +68,8 @@ Set the `variant` attribute to change the alert's variant.
 </sl-alert>
 ```
 
-```jsx:react
-import SlAlert from '@shoelace-style/shoelace/dist/react/alert';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlAlert, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -130,7 +123,7 @@ const App = () => (
 
 Add the `closable` attribute to show a close button that will hide the alert.
 
-```html:preview
+```html preview
 <sl-alert variant="primary" open closable class="alert-closable">
   <sl-icon slot="icon" name="info-circle"></sl-icon>
   You can close this alert any time!
@@ -144,10 +137,9 @@ Add the `closable` attribute to show a close button that will hide the alert.
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlAlert from '@shoelace-style/shoelace/dist/react/alert';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+import { SlAlert, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(true);
@@ -170,12 +162,12 @@ const App = () => {
 
 Icons are optional. Simply omit the `icon` slot if you don't want them.
 
-```html:preview
+```html preview
 <sl-alert variant="primary" open> Nothing fancy here, just a simple alert. </sl-alert>
 ```
 
-```jsx:react
-import SlAlert from '@shoelace-style/shoelace/dist/react/alert';
+```jsx react
+import { SlAlert } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlAlert variant="primary" open>
@@ -188,7 +180,7 @@ const App = () => (
 
 Set the `duration` attribute to automatically hide an alert after a period of time. This is useful for alerts that don't require acknowledgement.
 
-```html:preview
+```html preview
 <div class="alert-duration">
   <sl-button variant="primary">Show Alert</sl-button>
 
@@ -213,11 +205,9 @@ Set the `duration` attribute to automatically hide an alert after a period of ti
 </style>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlAlert from '@shoelace-style/shoelace/dist/react/alert';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+import { SlAlert, SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .alert-duration sl-alert {
@@ -253,7 +243,7 @@ To display an alert as a toast notification, or "toast", create the alert and ca
 
 You should always use the `closable` attribute so users can dismiss the notification. It's also common to set a reasonable `duration` when the notification doesn't require acknowledgement.
 
-```html:preview
+```html preview
 <div class="alert-toast">
   <sl-button variant="primary">Primary</sl-button>
   <sl-button variant="success">Success</sl-button>
@@ -304,11 +294,9 @@ You should always use the `closable` attribute so users can dismiss the notifica
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useRef } from 'react';
-import SlAlert from '@shoelace-style/shoelace/dist/react/alert';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+import { SlAlert, SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 function showToast(alert) {
   alert.toast();
@@ -386,7 +374,7 @@ const App = () => {
 
 For convenience, you can create a utility that emits toast notifications with a function call rather than composing them in your HTML. To do this, generate the alert with JavaScript, append it to the body, and call the `toast()` method as shown in the example below.
 
-```html:preview
+```html preview
 <div class="alert-toast-wrapper">
   <sl-button variant="primary">Create Toast</sl-button>
 </div>
@@ -438,6 +426,6 @@ By default, the toast stack is positioned at the top-right of the viewport. You
 }
 ```
 
-:::tip
-By design, it is not possible to show toasts in more than one stack simultaneously. Such behavior is confusing and makes for a poor user experience.
-:::
+?> By design, it is not possible to show toasts in more than one stack simultaneously. Such behavior is confusing and makes for a poor user experience.
+
+[component-metadata:sl-alert]

docs/components/animated-image.md

@@ -1,19 +1,16 @@
----
-meta:
-  title: Animated Image
-  description: A component for displaying animated GIFs and WEBPs that play and pause on interaction.
-layout: component
----
+# Animated Image
 
-```html:preview
+[component-header:sl-animated-image]
+
+```html preview
 <sl-animated-image
   src="https://shoelace.style/assets/images/walk.gif"
   alt="Animation of untied shoes walking on pavement"
 ></sl-animated-image>
 ```
 
-```jsx:react
-import SlAnimatedImage from '@shoelace-style/shoelace/dist/react/animated-image';
+```jsx react
+import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlAnimatedImage
@@ -23,9 +20,7 @@ const App = () => (
 );
 ```
 
-:::tip
-This component uses `<canvas>` to draw freeze frames, so images are subject to [cross-origin restrictions](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image).
-:::
+?> This component uses `<canvas>` to draw freeze frames, so images are subject to [cross-origin restrictions](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image).
 
 ## Examples
 
@@ -33,15 +28,15 @@ This component uses `<canvas>` to draw freeze frames, so images are subject to [
 
 Both GIF and WEBP images are supported.
 
-```html:preview
+```html preview
 <sl-animated-image
   src="https://shoelace.style/assets/images/tie.webp"
   alt="Animation of a shoe being tied"
 ></sl-animated-image>
 ```
 
-```jsx:react
-import SlAnimatedImage from '@shoelace-style/shoelace/dist/react/animated-image';
+```jsx react
+import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlAnimatedImage src="https://shoelace.style/assets/images/tie.webp" alt="Animation of a shoe being tied" />
@@ -52,7 +47,7 @@ const App = () => (
 
 To set a custom size, apply a width and/or height to the host element.
 
-```html:preview
+```html preview
 <sl-animated-image
   src="https://shoelace.style/assets/images/walk.gif"
   alt="Animation of untied shoes walking on pavement"
@@ -61,10 +56,8 @@ To set a custom size, apply a width and/or height to the host element.
 </sl-animated-image>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlAnimatedImage from '@shoelace-style/shoelace/dist/react/animated-image';
+```jsx react
+import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlAnimatedImage
@@ -75,13 +68,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Customizing the Control Box
 
 You can change the appearance and location of the control box by targeting the `control-box` part in your styles.
 
-```html:preview
+```html preview
 <sl-animated-image
   src="https://shoelace.style/assets/images/walk.gif"
   alt="Animation of untied shoes walking on pavement"
@@ -101,8 +92,8 @@ You can change the appearance and location of the control box by targeting the `
 </style>
 ```
 
-```jsx:react
-import SlAnimatedImage from '@shoelace-style/shoelace/dist/react/animated-image';
+```jsx react
+import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .animated-image-custom-control-box::part(control-box) {
@@ -128,3 +119,5 @@ const App = () => (
   </>
 );
 ```
+
+[component-metadata:sl-animated-image]

docs/components/animation.md

@@ -1,13 +1,10 @@
----
-meta:
-  title: Animation
-  description: Animate elements declaratively with nearly 100 baked-in presets, or roll your own with custom keyframes.
-layout: component
----
+# Animation
+
+[component-header:sl-animation]
 
 To animate an element, wrap it in `<sl-animation>` and set an animation `name`. The animation will not start until you add the `play` attribute. Refer to the [properties table](#properties) for a list of all animation options.
 
-```html:preview
+```html preview
 <div class="animation-overview">
   <sl-animation name="bounce" duration="2000" play><div class="box"></div></sl-animation>
   <sl-animation name="jello" duration="2000" play><div class="box"></div></sl-animation>
@@ -26,8 +23,8 @@ To animate an element, wrap it in `<sl-animation>` and set an animation `name`.
 </style>
 ```
 
-```jsx:react
-import SlAnimation from '@shoelace-style/shoelace/dist/react/animation';
+```jsx react
+import { SlAnimation } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .animation-overview .box {
@@ -61,9 +58,7 @@ const App = () => (
 );
 ```
 
-:::tip
-The animation will only be applied to the first child element found in `<sl-animation>`.
-:::
+?> The animation will only be applied to the first child element found in `<sl-animation>`.
 
 ## Examples
 
@@ -71,7 +66,7 @@ The animation will only be applied to the first child element found in `<sl-anim
 
 This example demonstrates all of the baked-in animations and easings. Animations are based on those found in the popular [Animate.css](https://animate.style/) library.
 
-```html:preview
+```html preview
 <div class="animation-sandbox">
   <sl-animation name="bounce" easing="ease-in-out" duration="2000" play>
     <div class="box"></div>
@@ -138,7 +133,7 @@ This example demonstrates all of the baked-in animations and easings. Animations
 
 Use an [Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) to control the animation when an element enters or exits the viewport. For example, scroll the box below in and out of your screen. The animation stops when the box exits the viewport and restarts each time it enters the viewport.
 
-```html:preview
+```html preview
 <div class="animation-scroll">
   <sl-animation name="jackInTheBox" duration="2000" iterations="1"><div class="box"></div></sl-animation>
 </div>
@@ -171,9 +166,9 @@ Use an [Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/
 </style>
 ```
 
-```jsx:react
+```jsx react
 import { useEffect, useRef, useState } from 'react';
-import SlAnimation from '@shoelace-style/shoelace/dist/react/animation';
+import { SlAnimation } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .animation-scroll {
@@ -225,7 +220,7 @@ const App = () => {
 
 Supply your own [keyframe formats](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats) to build custom animations.
 
-```html:preview
+```html preview
 <div class="animation-keyframes">
   <sl-animation easing="ease-in-out" duration="2000" play>
     <div class="box"></div>
@@ -261,8 +256,8 @@ Supply your own [keyframe formats](https://developer.mozilla.org/en-US/docs/Web/
 </style>
 ```
 
-```jsx:react
-import SlAnimation from '@shoelace-style/shoelace/dist/react/animation';
+```jsx react
+import { SlAnimation } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .animation-keyframes .box {
@@ -309,7 +304,7 @@ const App = () => (
 
 Animations won't play until you apply the `play` attribute. You can omit it initially, then apply it on demand such as after a user interaction. In this example, the button will animate once every time the button is clicked.
 
-```html:preview
+```html preview
 <div class="animation-form">
   <sl-animation name="rubberBand" duration="1000" iterations="1">
     <sl-button variant="primary">Click me</sl-button>
@@ -327,10 +322,9 @@ Animations won't play until you apply the `play` attribute. You can omit it init
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlAnimation from '@shoelace-style/shoelace/dist/react/animation';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
+import { SlAnimation, SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [play, setPlay] = useState(false);
@@ -346,3 +340,5 @@ const App = () => {
   );
 };
 ```
+
+[component-metadata:sl-animation]

docs/components/avatar.md

@@ -1,18 +1,15 @@
----
-meta:
-  title: Avatar
-  description: Avatars are used to represent a person or object.
-layout: component
----
+# Avatar
+
+[component-header:sl-avatar]
 
 By default, a generic icon will be shown. You can personalize avatars by adding custom icons, initials, and images. You should always provide a `label` for assistive devices.
 
-```html:preview
+```html preview
 <sl-avatar label="User avatar"></sl-avatar>
 ```
 
-```jsx:react
-import SlAvatar from '@shoelace-style/shoelace/dist/react/avatar';
+```jsx react
+import { SlAvatar } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlAvatar label="User avatar" />;
 ```
@@ -24,7 +21,7 @@ const App = () => <SlAvatar label="User avatar" />;
 To use an image for the avatar, set the `image` and `label` attributes. This will take priority and be shown over initials and icons.
 Avatar images can be lazily loaded by setting the `loading` attribute to `lazy`.
 
-```html:preview
+```html preview
 <sl-avatar
   image="https://images.unsplash.com/photo-1529778873920-4da4926a72c2?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
   label="Avatar of a gray tabby kitten looking down"
@@ -36,8 +33,8 @@ Avatar images can be lazily loaded by setting the `loading` attribute to `lazy`.
 ></sl-avatar>
 ```
 
-```jsx:react
-import SlAvatar from '@shoelace-style/shoelace/dist/react/avatar';
+```jsx react
+import { SlAvatar } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlAvatar
@@ -56,12 +53,12 @@ const App = () => (
 
 When you don't have an image to use, you can set the `initials` attribute to show something more personalized than an icon.
 
-```html:preview
+```html preview
 <sl-avatar initials="SL" label="Avatar with initials: SL"></sl-avatar>
 ```
 
-```jsx:react
-import SlAvatar from '@shoelace-style/shoelace/dist/react/avatar';
+```jsx react
+import { SlAvatar } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlAvatar initials="SL" label="Avatar with initials: SL" />;
 ```
@@ -70,7 +67,7 @@ const App = () => <SlAvatar initials="SL" label="Avatar with initials: SL" />;
 
 When no image or initials are set, an icon will be shown. The default avatar shows a generic "user" icon, but you can customize this with the `icon` slot.
 
-```html:preview
+```html preview
 <sl-avatar label="Avatar with an image icon">
   <sl-icon slot="icon" name="image"></sl-icon>
 </sl-avatar>
@@ -84,9 +81,8 @@ When no image or initials are set, an icon will be shown. The default avatar sho
 </sl-avatar>
 ```
 
-```jsx:react
-import SlAvatar from '@shoelace-style/shoelace/dist/react/avatar';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlAvatar, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -109,15 +105,14 @@ const App = () => (
 
 Avatars can be shaped using the `shape` attribute.
 
-```html:preview
+```html preview
 <sl-avatar shape="square" label="Square avatar"></sl-avatar>
 <sl-avatar shape="rounded" label="Rounded avatar"></sl-avatar>
 <sl-avatar shape="circle" label="Circle avatar"></sl-avatar>
 ```
 
-```jsx:react
-import SlAvatar from '@shoelace-style/shoelace/dist/react/avatar';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlAvatar, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -132,7 +127,7 @@ const App = () => (
 
 You can group avatars with a few lines of CSS.
 
-```html:preview
+```html preview
 <div class="avatar-group">
   <sl-avatar
     image="https://images.unsplash.com/photo-1490150028299-bf57d78394e0?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&q=80&crop=right"
@@ -166,9 +161,8 @@ You can group avatars with a few lines of CSS.
 </style>
 ```
 
-```jsx:react
-import SlAvatar from '@shoelace-style/shoelace/dist/react/avatar';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlAvatar, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .avatar-group sl-avatar:not(:first-of-type) {
@@ -208,3 +202,5 @@ const App = () => (
   </>
 );
 ```
+
+[component-metadata:sl-avatar]

docs/components/badge.md

@@ -1,16 +1,13 @@
----
-meta:
-  title: Badge
-  description: Badges are used to draw attention and display statuses or counts.
-layout: component
----
+# Badge
 
-```html:preview
+[component-header:sl-badge]
+
+```html preview
 <sl-badge>Badge</sl-badge>
 ```
 
-```jsx:react
-import SlBadge from '@shoelace-style/shoelace/dist/react/badge';
+```jsx react
+import { SlBadge } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlBadge>Badge</SlBadge>;
 ```
@@ -21,7 +18,7 @@ const App = () => <SlBadge>Badge</SlBadge>;
 
 Set the `variant` attribute to change the badge's variant.
 
-```html:preview
+```html preview
 <sl-badge variant="primary">Primary</sl-badge>
 <sl-badge variant="success">Success</sl-badge>
 <sl-badge variant="neutral">Neutral</sl-badge>
@@ -29,8 +26,8 @@ Set the `variant` attribute to change the badge's variant.
 <sl-badge variant="danger">Danger</sl-badge>
 ```
 
-```jsx:react
-import SlBadge from '@shoelace-style/shoelace/dist/react/badge';
+```jsx react
+import { SlBadge } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -47,7 +44,7 @@ const App = () => (
 
 Use the `pill` attribute to give badges rounded edges.
 
-```html:preview
+```html preview
 <sl-badge variant="primary" pill>Primary</sl-badge>
 <sl-badge variant="success" pill>Success</sl-badge>
 <sl-badge variant="neutral" pill>Neutral</sl-badge>
@@ -55,8 +52,8 @@ Use the `pill` attribute to give badges rounded edges.
 <sl-badge variant="danger" pill>Danger</sl-badge>
 ```
 
-```jsx:react
-import SlBadge from '@shoelace-style/shoelace/dist/react/badge';
+```jsx react
+import { SlBadge } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -83,7 +80,7 @@ const App = () => (
 
 Use the `pulse` attribute to draw attention to the badge with a subtle animation.
 
-```html:preview
+```html preview
 <div class="badge-pulse">
   <sl-badge variant="primary" pill pulse>1</sl-badge>
   <sl-badge variant="success" pill pulse>1</sl-badge>
@@ -99,8 +96,8 @@ Use the `pulse` attribute to draw attention to the badge with a subtle animation
 </style>
 ```
 
-```jsx:react
-import SlBadge from '@shoelace-style/shoelace/dist/react/badge';
+```jsx react
+import { SlBadge } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .badge-pulse sl-badge:not(:last-of-type) {
@@ -137,7 +134,7 @@ const App = () => (
 
 One of the most common use cases for badges is attaching them to buttons. To make this easier, badges will be automatically positioned at the top-right when they're a child of a button.
 
-```html:preview
+```html preview
 <sl-button>
   Requests
   <sl-badge pill>30</sl-badge>
@@ -154,11 +151,8 @@ One of the most common use cases for badges is attaching them to buttons. To mak
 </sl-button>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlBadge from '@shoelace-style/shoelace/dist/react/badge';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
+```jsx react
+import { SlBadge, SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -184,13 +178,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### With Menu Items
 
 When including badges in menu items, use the `suffix` slot to make sure they're aligned correctly.
 
-```html:preview
+```html preview
 <sl-menu style="max-width: 240px;">
   <sl-menu-label>Messages</sl-menu-label>
   <sl-menu-item>Comments <sl-badge slot="suffix" variant="neutral" pill>4</sl-badge></sl-menu-item>
@@ -198,14 +190,8 @@ When including badges in menu items, use the `suffix` slot to make sure they're
 </sl-menu>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlBadge from '@shoelace-style/shoelace/dist/react/badge';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
-import SlMenuLabel from '@shoelace-style/shoelace/dist/react/menu-label';
+```jsx react
+import { SlBadge, SlButton, SlMenu, SlMenuItem, SlMenuLabel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlMenu
@@ -232,4 +218,4 @@ const App = () => (
 );
 ```
 
-{% endraw %}
+[component-metadata:sl-badge]

docs/components/breadcrumb-item.md

@@ -1,11 +1,8 @@
----
-meta:
-  title: Breadcrumb Item
-  description: Breadcrumb Items are used inside breadcrumbs to represent different links.
-layout: component
----
+# Breadcrumb Item
 
-```html:preview
+[component-header:sl-breadcrumb-item]
+
+```html preview
 <sl-breadcrumb>
   <sl-breadcrumb-item>
     <sl-icon slot="prefix" name="house"></sl-icon>
@@ -16,10 +13,8 @@ layout: component
 </sl-breadcrumb>
 ```
 
-```jsx:react
-import SlBreadcrumb from '@shoelace-style/shoelace/dist/react/breadcrumb';
-import SlBreadcrumbItem from '@shoelace-style/shoelace/dist/react/breadcrumb-item';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlBreadcrumb, SlBreadcrumbItem, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlBreadcrumb>
@@ -33,6 +28,6 @@ const App = () => (
 );
 ```
 
-:::tip
-Additional demonstrations can be found in the [breadcrumb examples](/components/breadcrumb).
-:::
+?> Additional demonstrations can be found in the [breadcrumb examples](/components/breadcrumb).
+
+[component-metadata:sl-breadcrumb-item]

docs/components/breadcrumb.md

@@ -1,13 +1,10 @@
----
-meta:
-  title: Breadcrumb
-  description: Breadcrumbs provide a group of links so users can easily navigate a website's hierarchy.
-layout: component
----
+# Breadcrumb
+
+[component-header:sl-breadcrumb]
 
 Breadcrumbs are usually placed before a page's main content with the current page shown last to indicate the user's position in the navigation.
 
-```html:preview
+```html preview
 <sl-breadcrumb>
   <sl-breadcrumb-item>Catalog</sl-breadcrumb-item>
   <sl-breadcrumb-item>Clothing</sl-breadcrumb-item>
@@ -16,9 +13,8 @@ Breadcrumbs are usually placed before a page's main content with the current pag
 </sl-breadcrumb>
 ```
 
-```jsx:react
-import SlBreadcrumb from '@shoelace-style/shoelace/dist/react/breadcrumb';
-import SlBreadcrumbItem from '@shoelace-style/shoelace/dist/react/breadcrumb-item';
+```jsx react
+import { SlBreadcrumb, SlBreadcrumbItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlBreadcrumb>
@@ -38,7 +34,7 @@ By default, breadcrumb items are rendered as buttons so you can use them to navi
 
 For websites, you'll probably want to use links instead. You can make any breadcrumb item a link by applying an `href` attribute to it. Now, when the user activates it, they'll be taken to the corresponding page — no event listeners required.
 
-```html:preview
+```html preview
 <sl-breadcrumb>
   <sl-breadcrumb-item href="https://example.com/home">Homepage</sl-breadcrumb-item>
 
@@ -50,9 +46,8 @@ For websites, you'll probably want to use links instead. You can make any breadc
 </sl-breadcrumb>
 ```
 
-```jsx:react
-import SlBreadcrumb from '@shoelace-style/shoelace/dist/react/breadcrumb';
-import SlBreadcrumbItem from '@shoelace-style/shoelace/dist/react/breadcrumb-item';
+```jsx react
+import { SlBreadcrumb, SlBreadcrumbItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlBreadcrumb>
@@ -71,7 +66,7 @@ const App = () => (
 
 Use the `separator` slot to change the separator that goes between breadcrumb items. Icons work well, but you can also use text or an image.
 
-```html:preview
+```html preview
 <sl-breadcrumb>
   <sl-icon name="dot" slot="separator"></sl-icon>
   <sl-breadcrumb-item>First</sl-breadcrumb-item>
@@ -98,10 +93,9 @@ Use the `separator` slot to change the separator that goes between breadcrumb it
 </sl-breadcrumb>
 ```
 
-```jsx:react
+```jsx react
 import '@shoelace-style/shoelace/dist/components/icon/icon.js';
-import SlBreadcrumb from '@shoelace-style/shoelace/dist/react/breadcrumb';
-import SlBreadcrumbItem from '@shoelace-style/shoelace/dist/react/breadcrumb-item';
+import { SlBreadcrumb, SlBreadcrumbItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -137,7 +131,7 @@ const App = () => (
 
 Use the `prefix` slot to add content before any breadcrumb item.
 
-```html:preview
+```html preview
 <sl-breadcrumb>
   <sl-breadcrumb-item>
     <sl-icon slot="prefix" name="house"></sl-icon>
@@ -148,10 +142,8 @@ Use the `prefix` slot to add content before any breadcrumb item.
 </sl-breadcrumb>
 ```
 
-```jsx:react
-import SlBreadcrumb from '@shoelace-style/shoelace/dist/react/breadcrumb';
-import SlBreadcrumbItem from '@shoelace-style/shoelace/dist/react/breadcrumb-item';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlBreadcrumb, SlBreadcrumbItem, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlBreadcrumb>
@@ -169,7 +161,7 @@ const App = () => (
 
 Use the `suffix` slot to add content after any breadcrumb item.
 
-```html:preview
+```html preview
 <sl-breadcrumb>
   <sl-breadcrumb-item>Documents</sl-breadcrumb-item>
   <sl-breadcrumb-item>Policies</sl-breadcrumb-item>
@@ -180,10 +172,8 @@ Use the `suffix` slot to add content after any breadcrumb item.
 </sl-breadcrumb>
 ```
 
-```jsx:react
-import SlBreadcrumb from '@shoelace-style/shoelace/dist/react/breadcrumb';
-import SlBreadcrumbItem from '@shoelace-style/shoelace/dist/react/breadcrumb-item';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlBreadcrumb, SlBreadcrumbItem, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlBreadcrumb>
@@ -201,7 +191,7 @@ const App = () => (
 
 Dropdown menus can be placed in a prefix or suffix slot to provide additional options.
 
-```html:preview
+```html preview
 <sl-breadcrumb>
   <sl-breadcrumb-item>Homepage</sl-breadcrumb-item>
   <sl-breadcrumb-item>Our Services</sl-breadcrumb-item>
@@ -222,7 +212,7 @@ Dropdown menus can be placed in a prefix or suffix slot to provide additional op
 </sl-breadcrumb>
 ```
 
-```jsx:react
+```jsx react
 import {
   SlBreadcrumb,
   SlBreadcrumbItem,
@@ -256,3 +246,5 @@ const App = () => (
   </SlBreadcrumb>
 );
 ```
+
+[component-metadata:sl-breadcrumb]

docs/components/button-group.md

@@ -1,11 +1,8 @@
----
-meta:
-  title: Button Group
-  description: Button groups can be used to group related buttons into sections.
-layout: component
----
+# Button Group
 
-```html:preview
+[component-header:sl-button-group]
+
+```html preview
 <sl-button-group label="Alignment">
   <sl-button>Left</sl-button>
   <sl-button>Center</sl-button>
@@ -13,9 +10,8 @@ layout: component
 </sl-button-group>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlButtonGroup from '@shoelace-style/shoelace/dist/react/button-group';
+```jsx react
+import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlButtonGroup label="Alignment">
@@ -32,7 +28,7 @@ const App = () => (
 
 All button sizes are supported, but avoid mixing sizes within the same button group.
 
-```html:preview
+```html preview
 <sl-button-group label="Alignment">
   <sl-button size="small">Left</sl-button>
   <sl-button size="small">Center</sl-button>
@@ -56,9 +52,8 @@ All button sizes are supported, but avoid mixing sizes within the same button gr
 </sl-button-group>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlButtonGroup from '@shoelace-style/shoelace/dist/react/button-group';
+```jsx react
+import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -93,7 +88,7 @@ const App = () => (
 
 Theme buttons are supported through the button's `variant` attribute.
 
-```html:preview
+```html preview
 <sl-button-group label="Alignment">
   <sl-button variant="primary">Left</sl-button>
   <sl-button variant="primary">Center</sl-button>
@@ -133,9 +128,8 @@ Theme buttons are supported through the button's `variant` attribute.
 </sl-button-group>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlButtonGroup from '@shoelace-style/shoelace/dist/react/button-group';
+```jsx react
+import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -188,7 +182,7 @@ const App = () => (
 
 Pill buttons are supported through the button's `pill` attribute.
 
-```html:preview
+```html preview
 <sl-button-group label="Alignment">
   <sl-button size="small" pill>Left</sl-button>
   <sl-button size="small" pill>Center</sl-button>
@@ -212,9 +206,8 @@ Pill buttons are supported through the button's `pill` attribute.
 </sl-button-group>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlButtonGroup from '@shoelace-style/shoelace/dist/react/button-group';
+```jsx react
+import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -267,7 +260,7 @@ const App = () => (
 
 Dropdowns can be placed inside button groups as long as the trigger is an `<sl-button>` element.
 
-```html:preview
+```html preview
 <sl-button-group label="Example Button Group">
   <sl-button>Button</sl-button>
   <sl-button>Button</sl-button>
@@ -282,12 +275,8 @@ Dropdowns can be placed inside button groups as long as the trigger is an `<sl-b
 </sl-button-group>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlButtonGroup from '@shoelace-style/shoelace/dist/react/button-group';
-import SlDropdown from '@shoelace-style/shoelace/dist/react/dropdown';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlButton, SlButtonGroup, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlButtonGroup label="Example Button Group">
@@ -311,7 +300,7 @@ const App = () => (
 
 Create a split button using a button and a dropdown. Use a [visually hidden](/components/visually-hidden) label to ensure the dropdown is accessible to users with assistive devices.
 
-```html:preview
+```html preview
 <sl-button-group label="Example Button Group">
   <sl-button variant="primary">Save</sl-button>
   <sl-dropdown placement="bottom-end">
@@ -327,12 +316,8 @@ Create a split button using a button and a dropdown. Use a [visually hidden](/co
 </sl-button-group>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlButtonGroup from '@shoelace-style/shoelace/dist/react/button-group';
-import SlDropdown from '@shoelace-style/shoelace/dist/react/dropdown';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlButton, SlButtonGroup, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlButtonGroup label="Example Button Group">
@@ -353,7 +338,7 @@ const App = () => (
 
 Buttons can be wrapped in tooltips to provide more detail when the user interacts with them.
 
-```html:preview
+```html preview
 <sl-button-group label="Alignment">
   <sl-tooltip content="I'm on the left">
     <sl-button>Left</sl-button>
@@ -369,10 +354,8 @@ Buttons can be wrapped in tooltips to provide more detail when the user interact
 </sl-button-group>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlButtonGroup from '@shoelace-style/shoelace/dist/react/button-group';
-import SlTooltip from '@shoelace-style/shoelace/dist/react/tooltip';
+```jsx react
+import { SlButton, SlButtonGroup, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -397,7 +380,7 @@ const App = () => (
 
 Create interactive toolbars with button groups.
 
-```html:preview
+```html preview
 <div class="button-group-toolbar">
   <sl-button-group label="History">
     <sl-tooltip content="Undo">
@@ -440,11 +423,8 @@ Create interactive toolbars with button groups.
 </style>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlButtonGroup from '@shoelace-style/shoelace/dist/react/button-group';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlTooltip from '@shoelace-style/shoelace/dist/react/tooltip';
+```jsx react
+import { SlButton, SlButtonGroup, SlIcon, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .button-group-toolbar sl-button-group:not(:last-of-type) {
@@ -509,3 +489,5 @@ const App = () => (
   </>
 );
 ```
+
+[component-metadata:sl-button-group]

docs/components/button.md

@@ -1,16 +1,13 @@
----
-meta:
-  title: Button
-  description: Buttons represent actions that are available to the user.
-layout: component
----
+# Button
 
-```html:preview
+[component-header:sl-button]
+
+```html preview
 <sl-button>Button</sl-button>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
+```jsx react
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlButton>Button</SlButton>;
 ```
@@ -21,7 +18,7 @@ const App = () => <SlButton>Button</SlButton>;
 
 Use the `variant` attribute to set the button's variant.
 
-```html:preview
+```html preview
 <sl-button variant="default">Default</sl-button>
 <sl-button variant="primary">Primary</sl-button>
 <sl-button variant="success">Success</sl-button>
@@ -30,8 +27,8 @@ Use the `variant` attribute to set the button's variant.
 <sl-button variant="danger">Danger</sl-button>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
+```jsx react
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -49,14 +46,14 @@ const App = () => (
 
 Use the `size` attribute to change a button's size.
 
-```html:preview
+```html preview
 <sl-button size="small">Small</sl-button>
 <sl-button size="medium">Medium</sl-button>
 <sl-button size="large">Large</sl-button>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
+```jsx react
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -71,7 +68,7 @@ const App = () => (
 
 Use the `outline` attribute to draw outlined buttons with transparent backgrounds.
 
-```html:preview
+```html preview
 <sl-button variant="default" outline>Default</sl-button>
 <sl-button variant="primary" outline>Primary</sl-button>
 <sl-button variant="success" outline>Success</sl-button>
@@ -80,8 +77,8 @@ Use the `outline` attribute to draw outlined buttons with transparent background
 <sl-button variant="danger" outline>Danger</sl-button>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
+```jsx react
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -111,14 +108,14 @@ const App = () => (
 
 Use the `pill` attribute to give buttons rounded edges.
 
-```html:preview
+```html preview
 <sl-button size="small" pill>Small</sl-button>
 <sl-button size="medium" pill>Medium</sl-button>
 <sl-button size="large" pill>Large</sl-button>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
+```jsx react
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -139,7 +136,7 @@ const App = () => (
 
 Use the `circle` attribute to create circular icon buttons. When this attribute is set, the button expects a single `<sl-icon>` in the default slot.
 
-```html:preview
+```html preview
 <sl-button variant="default" size="small" circle>
   <sl-icon name="gear" label="Settings"></sl-icon>
 </sl-button>
@@ -153,9 +150,8 @@ Use the `circle` attribute to create circular icon buttons. When this attribute
 </sl-button>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -176,14 +172,14 @@ const App = () => (
 
 Use the `text` variant to create text buttons that share the same size as regular buttons but don't have backgrounds or borders.
 
-```html:preview
+```html preview
 <sl-button variant="text" size="small">Text</sl-button>
 <sl-button variant="text" size="medium">Text</sl-button>
 <sl-button variant="text" size="large">Text</sl-button>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
+```jsx react
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -202,17 +198,17 @@ const App = () => (
 
 ### Link Buttons
 
-It's often helpful to have a button that works like a link. This is possible by setting the `href` attribute, which will make the component render an `<a>` under the hood. This gives you all the default link behavior the browser provides (e.g. [[CMD/CTRL/SHIFT]] + [[CLICK]]) and exposes the `target` and `download` attributes.
+It's often helpful to have a button that works like a link. This is possible by setting the `href` attribute, which will make the component render an `<a>` under the hood. This gives you all the default link behavior the browser provides (e.g. <kbd>CMD/CTRL/SHIFT + CLICK</kbd>) and exposes the `target` and `download` attributes.
 
-```html:preview
+```html preview
 <sl-button href="https://example.com/">Link</sl-button>
 <sl-button href="https://example.com/" target="_blank">New Window</sl-button>
 <sl-button href="/assets/images/wordmark.svg" download="shoelace.svg">Download</sl-button>
 <sl-button href="https://example.com/" disabled>Disabled</sl-button>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
+```jsx react
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -230,24 +226,20 @@ const App = () => (
 );
 ```
 
-:::tip
-When a `target` is set, the link will receive `rel="noreferrer noopener"` for [security reasons](https://mathiasbynens.github.io/rel-noopener/).
-:::
+?> When a `target` is set, the link will receive `rel="noreferrer noopener"` for [security reasons](https://mathiasbynens.github.io/rel-noopener/).
 
 ### Setting a Custom Width
 
 As expected, buttons can be given a custom width by setting the `width` attribute. This is useful for making buttons span the full width of their container on smaller screens.
 
-```html:preview
+```html preview
 <sl-button variant="default" size="small" style="width: 100%; margin-bottom: 1rem;">Small</sl-button>
 <sl-button variant="default" size="medium" style="width: 100%; margin-bottom: 1rem;">Medium</sl-button>
 <sl-button variant="default" size="large" style="width: 100%;">Large</sl-button>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
+```jsx react
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -264,13 +256,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Prefix and Suffix Icons
 
 Use the `prefix` and `suffix` slots to add icons.
 
-```html:preview
+```html preview
 <sl-button variant="default" size="small">
   <sl-icon slot="prefix" name="gear"></sl-icon>
   Settings
@@ -324,9 +314,8 @@ Use the `prefix` and `suffix` slots to add icons.
 </sl-button>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -391,14 +380,14 @@ const App = () => (
 
 Use the `caret` attribute to add a dropdown indicator when a button will trigger a dropdown, menu, or popover.
 
-```html:preview
+```html preview
 <sl-button size="small" caret>Small</sl-button>
 <sl-button size="medium" caret>Medium</sl-button>
 <sl-button size="large" caret>Large</sl-button>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
+```jsx react
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -419,7 +408,7 @@ const App = () => (
 
 Use the `loading` attribute to make a button busy. The width will remain the same as before, preventing adjacent elements from moving around. Clicks will be suppressed until the loading state is removed.
 
-```html:preview
+```html preview
 <sl-button variant="default" loading>Default</sl-button>
 <sl-button variant="primary" loading>Primary</sl-button>
 <sl-button variant="success" loading>Success</sl-button>
@@ -428,8 +417,8 @@ Use the `loading` attribute to make a button busy. The width will remain the sam
 <sl-button variant="danger" loading>Danger</sl-button>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
+```jsx react
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -457,9 +446,9 @@ const App = () => (
 
 ### Disabled
 
-Use the `disabled` attribute to disable a button.
+Use the `disabled` attribute to disable a button. Clicks will be suppressed until the disabled state is removed.
 
-```html:preview
+```html preview
 <sl-button variant="default" disabled>Default</sl-button>
 <sl-button variant="primary" disabled>Primary</sl-button>
 <sl-button variant="success" disabled>Success</sl-button>
@@ -468,8 +457,8 @@ Use the `disabled` attribute to disable a button.
 <sl-button variant="danger" disabled>Danger</sl-button>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
+```jsx react
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -504,7 +493,7 @@ const App = () => (
 
 This example demonstrates how to style buttons using a custom class. This is the recommended approach if you need to add additional variations. To customize an existing variation, modify the selector to target the button's `variant` attribute instead of a class (e.g. `sl-button[variant="primary"]`).
 
-```html:preview
+```html preview
 <sl-button class="pink">Pink Button</sl-button>
 
 <style>
@@ -543,3 +532,5 @@ This example demonstrates how to style buttons using a custom class. This is the
   }
 </style>
 ```
+
+[component-metadata:sl-button]

docs/components/card.md

@@ -1,11 +1,8 @@
----
-meta:
-  title: Card
-  description: Cards can be used to group related subjects in a container.
-layout: component
----
+# Card
 
-```html:preview
+[component-header:sl-card]
+
+```html preview
 <sl-card class="card-overview">
   <img
     slot="image"
@@ -40,10 +37,8 @@ layout: component
 </style>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlCard from '@shoelace-style/shoelace/dist/react/card';
-import SlRating from '@shoelace-style/shoelace/dist/react/rating';
+```jsx react
+import { SlButton, SlCard, SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .card-overview {
@@ -55,8 +50,8 @@ const css = `
   }
 
   .card-overview [slot="footer"] {
-    display: flex;
-    justify-content: space-between;
+    display: flex; 
+    justify-content: space-between; 
     align-items: center;
   }
 `;
@@ -89,11 +84,11 @@ const App = () => (
 
 ## Examples
 
-### Basic Card
+## Basic Card
 
 Basic cards aren't very exciting, but they can display any content you want them to.
 
-```html:preview
+```html preview
 <sl-card class="card-basic">
   This is just a basic card. No image, no header, and no footer. Just your content.
 </sl-card>
@@ -105,8 +100,8 @@ Basic cards aren't very exciting, but they can display any content you want them
 </style>
 ```
 
-```jsx:react
-import SlCard from '@shoelace-style/shoelace/dist/react/card';
+```jsx react
+import { SlCard } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .card-basic {
@@ -125,11 +120,11 @@ const App = () => (
 );
 ```
 
-### Card with Header
+## Card with Header
 
 Headers can be used to display titles and more.
 
-```html:preview
+```html preview
 <sl-card class="card-header">
   <div slot="header">
     Header Title
@@ -160,9 +155,8 @@ Headers can be used to display titles and more.
 </style>
 ```
 
-```jsx:react
-import SlCard from '@shoelace-style/shoelace/dist/react/card';
-import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';
+```jsx react
+import { SlCard, SlIconButton } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .card-header {
@@ -170,8 +164,8 @@ const css = `
   }
 
   .card-header [slot="header"] {
-    display: flex;
-    align-items: center;
+    display: flex; 
+    align-items: center; 
     justify-content: space-between;
   }
 
@@ -199,11 +193,11 @@ const App = () => (
 );
 ```
 
-### Card with Footer
+## Card with Footer
 
 Footers can be used to display actions, summaries, or other relevant content.
 
-```html:preview
+```html preview
 <sl-card class="card-footer">
   This card has a footer. You can put all sorts of things in it!
 
@@ -226,10 +220,8 @@ Footers can be used to display actions, summaries, or other relevant content.
 </style>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlCard from '@shoelace-style/shoelace/dist/react/card';
-import SlRating from '@shoelace-style/shoelace/dist/react/rating';
+```jsx react
+import { SlButton, SlCard, SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .card-footer {
@@ -237,8 +229,8 @@ const css = `
   }
 
   .card-footer [slot="footer"] {
-    display: flex;
-    justify-content: space-between;
+    display: flex; 
+    justify-content: space-between; 
     align-items: center;
   }
 `;
@@ -260,11 +252,11 @@ const App = () => (
 );
 ```
 
-### Images
+## Images
 
 Cards accept an `image` slot. The image is displayed atop the card and stretches to fit.
 
-```html:preview
+```html preview
 <sl-card class="card-image">
   <img
     slot="image"
@@ -281,8 +273,8 @@ Cards accept an `image` slot. The image is displayed atop the card and stretches
 </style>
 ```
 
-```jsx:react
-import SlCard from '@shoelace-style/shoelace/dist/react/card';
+```jsx react
+import { SlCard } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .card-image {
@@ -305,3 +297,5 @@ const App = () => (
   </>
 );
 ```
+
+[component-metadata:sl-card]

docs/components/carousel-item.md

@@ -1,11 +1,8 @@
----
-meta:
-  title: Carousel Item
-  description: A carousel item represent a slide within a carousel.
-layout: component
----
+# Carousel Item
 
-```html:preview
+[component-header:sl-carousel-item]
+
+```html preview
 <sl-carousel pagination>
   <sl-carousel-item>
     <img
@@ -40,9 +37,8 @@ layout: component
 </sl-carousel>
 ```
 
-```jsx:react
-import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
-import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
+```jsx react
+import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlCarousel pagination>
@@ -80,6 +76,6 @@ const App = () => (
 );
 ```
 
-:::tip
-Additional demonstrations can be found in the [carousel examples](/components/carousel).
-:::
+?> Additional demonstrations can be found in the [carousel examples](/components/carousel).
+
+[component-metadata:sl-carousel-item]

docs/components/carousel.md

@@ -1,11 +1,8 @@
----
-meta:
-  title: Carousel
-  description: Carousels display an arbitrary number of content slides along a horizontal or vertical axis.
-layout: component
----
+# Carousel
 
-```html:preview
+[component-header:sl-carousel]
+
+```html preview
 <sl-carousel pagination navigation mouse-dragging loop>
   <sl-carousel-item>
     <img
@@ -40,9 +37,8 @@ layout: component
 </sl-carousel>
 ```
 
-```jsx:react
-import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
-import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
+```jsx react
+import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -88,7 +84,7 @@ const App = () => (
 
 Use the `pagination` attribute to show the total number of slides and the current slide as a set of interactive dots.
 
-```html:preview
+```html preview
 <sl-carousel pagination>
   <sl-carousel-item>
     <img
@@ -123,9 +119,8 @@ Use the `pagination` attribute to show the total number of slides and the curren
 </sl-carousel>
 ```
 
-```jsx:react
-import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
-import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
+```jsx react
+import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlCarousel pagination>
@@ -167,7 +162,7 @@ const App = () => (
 
 Use the `navigation` attribute to show previous and next buttons.
 
-```html:preview
+```html preview
 <sl-carousel navigation>
   <sl-carousel-item>
     <img
@@ -202,9 +197,8 @@ Use the `navigation` attribute to show previous and next buttons.
 </sl-carousel>
 ```
 
-```jsx:react
-import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
-import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
+```jsx react
+import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlCarousel navigation>
@@ -246,7 +240,7 @@ const App = () => (
 
 By default, the carousel will not advanced beyond the first and last slides. You can change this behavior and force the carousel to "wrap" with the `loop` attribute.
 
-```html:preview
+```html preview
 <sl-carousel loop navigation pagination>
   <sl-carousel-item>
     <img
@@ -281,9 +275,8 @@ By default, the carousel will not advanced beyond the first and last slides. You
 </sl-carousel>
 ```
 
-```jsx:react
-import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
-import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
+```jsx react
+import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlCarousel loop navigation pagination>
@@ -325,7 +318,7 @@ const App = () => (
 
 The carousel will automatically advance when the `autoplay` attribute is used. To change how long a slide is shown before advancing, set `autoplay-interval` to the desired number of milliseconds. For best results, use the `loop` attribute when autoplay is enabled. Note that autoplay will pause while the user interacts with the carousel.
 
-```html:preview
+```html preview
 <sl-carousel autoplay loop pagination>
   <sl-carousel-item>
     <img
@@ -360,9 +353,8 @@ The carousel will automatically advance when the `autoplay` attribute is used. T
 </sl-carousel>
 ```
 
-```jsx:react
-import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
-import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
+```jsx react
+import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlCarousel autoplay loop pagination>
@@ -406,7 +398,7 @@ The carousel uses [scroll snap](https://developer.mozilla.org/en-US/docs/Web/CSS
 
 This example is best demonstrated using a mouse. Try clicking and dragging the slide to move it. Then toggle the switch and try again.
 
-```html:preview
+```html preview
 <div class="mouse-dragging">
   <sl-carousel pagination>
     <sl-carousel-item>
@@ -457,12 +449,9 @@ This example is best demonstrated using a mouse. Try clicking and dragging the s
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
-import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
+import { SlCarousel, SlCarouselItem, SlDivider, SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [isEnabled, setIsEnabled] = useState(false);
@@ -514,9 +503,9 @@ const App = () => {
 
 ### Multiple Slides Per View
 
-The `slides-per-page` attribute makes it possible to display multiple slides at a time. You can also use the `slides-per-move` attribute to advance more than once slide at a time, if desired.
+The `slides-per-view` attribute makes it possible to display multiple slides at a time. You can also use the `slides-per-move` attribute to advance more than once slide at a time, if desired.
 
-```html:preview
+```html preview
 <sl-carousel navigation pagination slides-per-page="2" slides-per-move="2">
   <sl-carousel-item style="background: var(--sl-color-red-200);">Slide 1</sl-carousel-item>
   <sl-carousel-item style="background: var(--sl-color-orange-200);">Slide 2</sl-carousel-item>
@@ -527,11 +516,8 @@ The `slides-per-page` attribute makes it possible to display multiple slides at
 </sl-carousel>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
-import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
+```jsx react
+import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlCarousel navigation pagination slidesPerPage={2} slidesPerMove={2}>
@@ -545,13 +531,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Adding and Removing Slides
 
 The content of the carousel can be changed by adding or removing carousel items. The carousel will update itself automatically.
 
-```html:preview
+```html preview
 <sl-carousel class="dynamic-carousel" pagination navigation>
   <sl-carousel-item style="background: var(--sl-color-red-200)">Slide 1</sl-carousel-item>
   <sl-carousel-item style="background: var(--sl-color-orange-200)">Slide 2</sl-carousel-item>
@@ -619,12 +603,9 @@ The content of the carousel can be changed by adding or removing carousel items.
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
-import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
+import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .dynamic-carousel {
@@ -680,13 +661,11 @@ const App = () => {
 };
 ```
 
-{% endraw %}
-
 ### Vertical Scrolling
 
 Setting the `orientation` attribute to `vertical` will render the carousel in a vertical layout. If the content of your slides vary in height, you will need to set amn explicit `height` or `max-height` on the carousel using CSS.
 
-```html:preview
+```html preview
 <sl-carousel class="vertical" pagination orientation="vertical">
   <sl-carousel-item>
     <img
@@ -739,9 +718,8 @@ Setting the `orientation` attribute to `vertical` will render the carousel in a
 </style>
 ```
 
-```jsx:react
-import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
-import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
+```jsx react
+import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .vertical {
@@ -805,7 +783,7 @@ const App = () => (
 
 Use the `--aspect-ratio` custom property to customize the size of the carousel's viewport.
 
-```html:preview
+```html preview
 <sl-carousel class="aspect-ratio" navigation pagination style="--aspect-ratio: 3/2;">
   <sl-carousel-item>
     <img
@@ -859,15 +837,9 @@ Use the `--aspect-ratio` custom property to customize the size of the carousel's
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
-import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
+import { SlCarousel, SlCarouselItem, SlDivider, SlSelect, SlOption } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [aspectRatio, setAspectRatio] = useState('3/2');
@@ -926,13 +898,11 @@ const App = () => {
 };
 ```
 
-{% endraw %}
-
 ### Scroll Hint
 
 Use the `--scroll-hint` custom property to add inline padding in horizontal carousels and block padding in vertical carousels. This will make the closest slides slightly visible, hinting that there are more items in the carousel.
 
-```html:preview
+```html preview
 <sl-carousel class="scroll-hint" pagination style="--scroll-hint: 10%;">
   <sl-carousel-item>
     <img
@@ -967,14 +937,9 @@ Use the `--scroll-hint` custom property to add inline padding in horizontal caro
 </sl-carousel>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
-import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+import { SlCarousel, SlCarouselItem, SlDivider, SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -1014,13 +979,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Gallery Example
 
 The carousel has a robust API that makes it possible to extend and customize. This example syncs the active slide with a set of thumbnails, effectively creating a gallery-style carousel.
 
-```html:preview
+```html preview
 <sl-carousel class="carousel-thumbnails" navigation loop>
   <sl-carousel-item>
     <img
@@ -1135,12 +1098,9 @@ The carousel has a robust API that makes it possible to extend and customize. Th
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useRef } from 'react';
-import SlCarousel from '@shoelace-style/shoelace/dist/react/carousel';
-import SlCarouselItem from '@shoelace-style/shoelace/dist/react/carousel-item';
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+import { SlCarousel, SlCarouselItem, SlDivider, SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .carousel-thumbnails {
@@ -1257,3 +1217,5 @@ const App = () => {
   );
 };
 ```
+
+[component-metadata:sl-carousel]

docs/components/checkbox.md

@@ -1,23 +1,18 @@
----
-meta:
-  title: Checkbox
-  description: Checkboxes allow the user to toggle an option on or off.
-layout: component
----
+# Checkbox
 
-```html:preview
+[component-header:sl-checkbox]
+
+```html preview
 <sl-checkbox>Checkbox</sl-checkbox>
 ```
 
-```jsx:react
-import SlCheckbox from '@shoelace-style/shoelace/dist/react/checkbox';
+```jsx react
+import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlCheckbox>Checkbox</SlCheckbox>;
 ```
 
-:::tip
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
-:::
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
@@ -25,12 +20,12 @@ This component works with standard `<form>` elements. Please refer to the sectio
 
 Use the `checked` attribute to activate the checkbox.
 
-```html:preview
+```html preview
 <sl-checkbox checked>Checked</sl-checkbox>
 ```
 
-```jsx:react
-import SlCheckbox from '@shoelace-style/shoelace/dist/react/checkbox';
+```jsx react
+import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlCheckbox checked>Checked</SlCheckbox>;
 ```
@@ -39,12 +34,12 @@ const App = () => <SlCheckbox checked>Checked</SlCheckbox>;
 
 Use the `indeterminate` attribute to make the checkbox indeterminate.
 
-```html:preview
+```html preview
 <sl-checkbox indeterminate>Indeterminate</sl-checkbox>
 ```
 
-```jsx:react
-import SlCheckbox from '@shoelace-style/shoelace/dist/react/checkbox';
+```jsx react
+import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlCheckbox indeterminate>Indeterminate</SlCheckbox>;
 ```
@@ -53,21 +48,21 @@ const App = () => <SlCheckbox indeterminate>Indeterminate</SlCheckbox>;
 
 Use the `disabled` attribute to disable the checkbox.
 
-```html:preview
+```html preview
 <sl-checkbox disabled>Disabled</sl-checkbox>
 ```
 
-```jsx:react
-import SlCheckbox from '@shoelace-style/shoelace/dist/react/checkbox';
+```jsx react
+import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlCheckbox disabled>Disabled</SlCheckbox>;
 ```
 
-### Sizes
+## Sizes
 
 Use the `size` attribute to change a checkbox's size.
 
-```html:preview
+```html preview
 <sl-checkbox size="small">Small</sl-checkbox>
 <br />
 <sl-checkbox size="medium">Medium</sl-checkbox>
@@ -75,8 +70,8 @@ Use the `size` attribute to change a checkbox's size.
 <sl-checkbox size="large">Large</sl-checkbox>
 ```
 
-```jsx:react
-import SlCheckbox from '@shoelace-style/shoelace/dist/react/checkbox';
+```jsx react
+import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -93,7 +88,7 @@ const App = () => (
 
 Use the `setCustomValidity()` method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.
 
-```html:preview
+```html preview
 <form class="custom-validity">
   <sl-checkbox>Check me</sl-checkbox>
   <br />
@@ -123,12 +118,9 @@ Use the `setCustomValidity()` method to set a custom validation message. This wi
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useEffect, useRef } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlCheckbox from '@shoelace-style/shoelace/dist/react/checkbox';
+import { SlButton, SlCheckbox } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const checkbox = useRef(null);
@@ -161,4 +153,4 @@ const App = () => {
 };
 ```
 
-{% endraw %}
+[component-metadata:sl-checkbox]

docs/components/color-picker.md

@@ -1,23 +1,18 @@
----
-meta:
-  title: Color Picker
-  description: Color pickers allow the user to select a color.
-layout: component
----
+# Color Picker
 
-```html:preview
+[component-header:sl-color-picker]
+
+```html preview
 <sl-color-picker label="Select a color"></sl-color-picker>
 ```
 
-```jsx:react
-import SlColorPicker from '@shoelace-style/shoelace/dist/react/color-picker';
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlColorPicker label="Select a color" />;
 ```
 
-:::tip
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
-:::
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
@@ -25,12 +20,12 @@ This component works with standard `<form>` elements. Please refer to the sectio
 
 Use the `value` attribute to set an initial value for the color picker.
 
-```html:preview
+```html preview
 <sl-color-picker value="#4a90e2" label="Select a color"></sl-color-picker>
 ```
 
-```jsx:react
-import SlColorPicker from '@shoelace-style/shoelace/dist/react/color-picker';
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlColorPicker value="#4a90e2" label="Select a color" />;
 ```
@@ -39,12 +34,12 @@ const App = () => <SlColorPicker value="#4a90e2" label="Select a color" />;
 
 Use the `opacity` attribute to enable the opacity slider. When this is enabled, the value will be displayed as HEXA, RGBA, HSLA, or HSVA based on `format`.
 
-```html:preview
+```html preview
 <sl-color-picker value="#f5a623ff" opacity label="Select a color"></sl-color-picker>
 ```
 
-```jsx:react
-import SlColorPicker from '@shoelace-style/shoelace/dist/react/color-picker';
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlColorPicker opacity label="Select a color" />;
 ```
@@ -55,15 +50,15 @@ Set the color picker's format with the `format` attribute. Valid options include
 
 To prevent users from toggling the format themselves, add the `no-format-toggle` attribute.
 
-```html:preview
+```html preview
 <sl-color-picker format="hex" value="#4a90e2" label="Select a color"></sl-color-picker>
 <sl-color-picker format="rgb" value="rgb(80, 227, 194)" label="Select a color"></sl-color-picker>
 <sl-color-picker format="hsl" value="hsl(290, 87%, 47%)" label="Select a color"></sl-color-picker>
 <sl-color-picker format="hsv" value="hsv(55, 89%, 97%)" label="Select a color"></sl-color-picker>
 ```
 
-```jsx:react
-import SlColorPicker from '@shoelace-style/shoelace/dist/react/color-picker';
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -79,24 +74,24 @@ const App = () => (
 
 Use the `swatches` attribute to add convenient presets to the color picker. Any format the color picker can parse is acceptable (including CSS color names), but each value must be separated by a semicolon (`;`). Alternatively, you can pass an array of color values to this property using JavaScript.
 
-```html:preview
+```html preview
 <sl-color-picker
   label="Select a color"
   swatches="
-    #d0021b; #f5a623; #f8e71c; #8b572a; #7ed321; #417505; #bd10e0; #9013fe;
+    #d0021b; #f5a623; #f8e71c; #8b572a; #7ed321; #417505; #bd10e0; #9013fe; 
     #4a90e2; #50e3c2; #b8e986; #000; #444; #888; #ccc; #fff;
   "
 ></sl-color-picker>
 ```
 
-```jsx:react
-import SlColorPicker from '@shoelace-style/shoelace/dist/react/color-picker';
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlColorPicker
     label="Select a color"
     swatches="
-      #d0021b; #f5a623; #f8e71c; #8b572a; #7ed321; #417505; #bd10e0; #9013fe;
+      #d0021b; #f5a623; #f8e71c; #8b572a; #7ed321; #417505; #bd10e0; #9013fe; 
       #4a90e2; #50e3c2; #b8e986; #000; #444; #888; #ccc; #fff;
     "
   />
@@ -107,14 +102,14 @@ const App = () => (
 
 Use the `size` attribute to change the color picker's trigger size.
 
-```html:preview
+```html preview
 <sl-color-picker size="small" label="Select a color"></sl-color-picker>
 <sl-color-picker size="medium" label="Select a color"></sl-color-picker>
 <sl-color-picker size="large" label="Select a color"></sl-color-picker>
 ```
 
-```jsx:react
-import SlColorPicker from '@shoelace-style/shoelace/dist/react/color-picker';
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -129,12 +124,14 @@ const App = () => (
 
 The color picker can be rendered inline instead of in a dropdown using the `inline` attribute.
 
-```html:preview
+```html preview
 <sl-color-picker inline label="Select a color"></sl-color-picker>
 ```
 
-```jsx:react
-import SlColorPicker from '@shoelace-style/shoelace/dist/react/color-picker';
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlColorPicker inline label="Select a color" />;
 ```
+
+[component-metadata:sl-color-picker]

docs/components/details.md

@@ -1,21 +1,18 @@
----
-meta:
-  title: Details
-  description: Details show a brief summary and expand to show additional content.
-layout: component
----
-
 <!-- cspell:dictionaries lorem-ipsum -->
 
-```html:preview
+# Details
+
+[component-header:sl-details]
+
+```html preview
 <sl-details summary="Toggle Me">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
   aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
 </sl-details>
 ```
 
-```jsx:react
-import SlDetails from '@shoelace-style/shoelace/dist/react/details';
+```jsx react
+import { SlDetails } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlDetails summary="Toggle Me">
@@ -31,15 +28,15 @@ const App = () => (
 
 Use the `disable` attribute to prevent the details from expanding.
 
-```html:preview
+```html preview
 <sl-details summary="Disabled" disabled>
   Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
   aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
 </sl-details>
 ```
 
-```jsx:react
-import SlDetails from '@shoelace-style/shoelace/dist/react/details';
+```jsx react
+import { SlDetails } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlDetails summary="Disabled" disabled>
@@ -53,7 +50,7 @@ const App = () => (
 
 Use the `expand-icon` and `collapse-icon` slots to change the expand and collapse icons, respectively. To disable the animation, override the `rotate` property on the `summary-icon` part as shown below.
 
-```html:preview
+```html preview
 <sl-details summary="Toggle Me" class="custom-icons">
   <sl-icon name="plus-square" slot="expand-icon"></sl-icon>
   <sl-icon name="dash-square" slot="collapse-icon"></sl-icon>
@@ -70,9 +67,8 @@ Use the `expand-icon` and `collapse-icon` slots to change the expand and collaps
 </style>
 ```
 
-```jsx:react
-import SlDetails from '@shoelace-style/shoelace/dist/react/details';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlDetails, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   sl-details.custom-icon::part(summary-icon) {
@@ -100,7 +96,7 @@ const App = () => (
 
 Details are designed to function independently, but you can simulate a group or "accordion" where only one is shown at a time by listening for the `sl-show` event.
 
-```html:preview
+```html preview
 <div class="details-group-example">
   <sl-details summary="First" open>
     Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
@@ -133,3 +129,5 @@ Details are designed to function independently, but you can simulate a group or
   }
 </style>
 ```
+
+[component-metadata:sl-details]

docs/components/dialog.md

@@ -1,13 +1,10 @@
----
-meta:
-  title: Dialog
-  description: 'Dialogs, sometimes called "modals", appear above the page and require the user''s immediate attention.'
-layout: component
----
-
 <!-- cspell:dictionaries lorem-ipsum -->
 
-```html:preview
+# Dialog
+
+[component-header:sl-dialog]
+
+```html preview
 <sl-dialog label="Dialog" class="dialog-overview">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   <sl-button slot="footer" variant="primary">Close</sl-button>
@@ -25,10 +22,9 @@ layout: component
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDialog from '@shoelace-style/shoelace/dist/react/dialog';
+import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -48,13 +44,19 @@ const App = () => {
 };
 ```
 
+## UX Tips
+
+- Use a dialog when you immediately require the user's attention, e.g. confirming a destructive action.
+- Always provide an obvious way for the user to dismiss the dialog.
+- Don't nest dialogs. It almost always leads to a poor experience for the user.
+
 ## Examples
 
 ### Custom Width
 
 Use the `--width` custom property to set the dialog's width.
 
-```html:preview
+```html preview
 <sl-dialog label="Dialog" class="dialog-width" style="--width: 50vw;">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   <sl-button slot="footer" variant="primary">Close</sl-button>
@@ -72,12 +74,9 @@ Use the `--width` custom property to set the dialog's width.
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDialog from '@shoelace-style/shoelace/dist/react/dialog';
+import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -97,13 +96,11 @@ const App = () => {
 };
 ```
 
-{% endraw %}
-
 ### Scrolling
 
 By design, a dialog's height will never exceed that of the viewport. As such, dialogs will not scroll with the page ensuring the header and footer are always accessible to the user.
 
-```html:preview
+```html preview
 <sl-dialog label="Dialog" class="dialog-scrolling">
   <div style="height: 150vh; border: dashed 2px var(--sl-color-neutral-200); padding: 0 1rem;">
     <p>Scroll down and give it a try! 👇</p>
@@ -123,12 +120,9 @@ By design, a dialog's height will never exceed that of the viewport. As such, di
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDialog from '@shoelace-style/shoelace/dist/react/dialog';
+import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -157,13 +151,11 @@ const App = () => {
 };
 ```
 
-{% endraw %}
-
 ### Header Actions
 
 The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/components/icon-button) if needed.
 
-```html:preview
+```html preview
 <sl-dialog label="Dialog" class="dialog-header-actions">
   <sl-icon-button class="new-window" slot="header-actions" name="box-arrow-up-right"></sl-icon-button>
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
@@ -184,11 +176,9 @@ The header shows a functional close button by default. You can use the `header-a
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDialog from '@shoelace-style/shoelace/dist/react/dialog';
-import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';
+import { SlButton, SlDialog, SlIconButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -216,13 +206,13 @@ const App = () => {
 
 ### Preventing the Dialog from Closing
 
-By default, dialogs will close when the user clicks the close button, clicks the overlay, or presses the [[Escape]] key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.
+By default, dialogs will close when the user clicks the close button, clicks the overlay, or presses the <kbd>Escape</kbd> key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.
 
 To keep the dialog open in such cases, you can cancel the `sl-request-close` event. When canceled, the dialog will remain open and pulse briefly to draw the user's attention to it.
 
-You can use `event.detail.source` to determine what triggered the request to close. This example prevents the dialog from closing when the overlay is clicked, but allows the close button or [[Escape]] to dismiss it.
+You can use `event.detail.source` to determine what triggered the request to close. This example prevents the dialog from closing when the overlay is clicked, but allows the close button or <kbd>Escape</kbd> to dismiss it.
 
-```html:preview
+```html preview
 <sl-dialog label="Dialog" class="dialog-deny-close">
   This dialog will not close when you click on the overlay.
   <sl-button slot="footer" variant="primary">Close</sl-button>
@@ -247,10 +237,9 @@ You can use `event.detail.source` to determine what triggered the request to clo
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDialog from '@shoelace-style/shoelace/dist/react/dialog';
+import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -281,7 +270,7 @@ const App = () => {
 
 By default, the dialog's panel will gain focus when opened. This allows a subsequent tab press to focus on the first tabbable element in the dialog. If you want a different element to have focus, add the `autofocus` attribute to it as shown below.
 
-```html:preview
+```html preview
 <sl-dialog label="Dialog" class="dialog-focus">
   <sl-input autofocus placeholder="I will have focus when the dialog is opened"></sl-input>
   <sl-button slot="footer" variant="primary">Close</sl-button>
@@ -300,11 +289,9 @@ By default, the dialog's panel will gain focus when opened. This allows a subseq
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDialog from '@shoelace-style/shoelace/dist/react/dialog';
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+import { SlButton, SlDialog, SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -324,6 +311,6 @@ const App = () => {
 };
 ```
 
-:::tip
-You can further customize initial focus behavior by canceling the `sl-initial-focus` event and setting focus yourself inside the event handler.
-:::
+?> You can further customize initial focus behavior by canceling the `sl-initial-focus` event and setting focus yourself inside the event handler.
+
+[component-metadata:sl-dialog]

docs/components/divider.md

@@ -1,16 +1,13 @@
----
-meta:
-  title: Divider
-  description: Dividers are used to visually separate or group elements.
-layout: component
----
+# Divider
 
-```html:preview
+[component-header:sl-divider]
+
+```html preview
 <sl-divider></sl-divider>
 ```
 
-```jsx:react
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
+```jsx react
+import { SlDivider } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlDivider />;
 ```
@@ -21,43 +18,35 @@ const App = () => <SlDivider />;
 
 Use the `--width` custom property to change the width of the divider.
 
-```html:preview
+```html preview
 <sl-divider style="--width: 4px;"></sl-divider>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
+```jsx react
+import { SlDivider } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlDivider style={{ '--width': '4px' }} />;
 ```
 
-{% endraw %}
-
 ### Color
 
 Use the `--color` custom property to change the color of the divider.
 
-```html:preview
+```html preview
 <sl-divider style="--color: tomato;"></sl-divider>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
+```jsx react
+import { SlDivider } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlDivider style={{ '--color': 'tomato' }} />;
 ```
 
-{% endraw %}
-
 ### Spacing
 
 Use the `--spacing` custom property to change the amount of space between the divider and it's neighboring elements.
 
-```html:preview
+```html preview
 <div style="text-align: center;">
   Above
   <sl-divider style="--spacing: 2rem;"></sl-divider>
@@ -65,10 +54,8 @@ Use the `--spacing` custom property to change the amount of space between the di
 </div>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
+```jsx react
+import { SlDivider } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -79,13 +66,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Vertical
 
 Add the `vertical` attribute to draw the divider in a vertical orientation. The divider will span the full height of its container. Vertical dividers work especially well inside of a flex container.
 
-```html:preview
+```html preview
 <div style="display: flex; align-items: center; height: 2rem;">
   First
   <sl-divider vertical></sl-divider>
@@ -95,10 +80,8 @@ Add the `vertical` attribute to draw the divider in a vertical orientation. The
 </div>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
+```jsx react
+import { SlDivider } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <div
@@ -117,13 +100,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Menu Dividers
 
 Use dividers in [menus](/components/menu) to visually group menu items.
 
-```html:preview
+```html preview
 <sl-menu style="max-width: 200px;">
   <sl-menu-item value="1">Option 1</sl-menu-item>
   <sl-menu-item value="2">Option 2</sl-menu-item>
@@ -135,12 +116,8 @@ Use dividers in [menus](/components/menu) to visually group menu items.
 </sl-menu>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlDivider, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlMenu style={{ maxWidth: '200px' }}>
@@ -155,4 +132,4 @@ const App = () => (
 );
 ```
 
-{% endraw %}
+[component-metadata:sl-divider]

docs/components/drawer.md

@@ -1,13 +1,10 @@
----
-meta:
-  title: Drawer
-  description: Drawers slide in from a container to expose additional options and information.
-layout: component
----
-
 <!-- cspell:dictionaries lorem-ipsum -->
 
-```html:preview
+# Drawer
+
+[component-header:sl-drawer]
+
+```html preview
 <sl-drawer label="Drawer" class="drawer-overview">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   <sl-button slot="footer" variant="primary">Close</sl-button>
@@ -25,10 +22,9 @@ layout: component
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDrawer from '@shoelace-style/shoelace/dist/react/drawer';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -54,7 +50,7 @@ const App = () => {
 
 By default, drawers slide in from the end. To make the drawer slide in from the start, set the `placement` attribute to `start`.
 
-```html:preview
+```html preview
 <sl-drawer label="Drawer" placement="start" class="drawer-placement-start">
   This drawer slides in from the start.
   <sl-button slot="footer" variant="primary">Close</sl-button>
@@ -72,10 +68,9 @@ By default, drawers slide in from the end. To make the drawer slide in from the
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDrawer from '@shoelace-style/shoelace/dist/react/drawer';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -99,7 +94,7 @@ const App = () => {
 
 To make the drawer slide in from the top, set the `placement` attribute to `top`.
 
-```html:preview
+```html preview
 <sl-drawer label="Drawer" placement="top" class="drawer-placement-top">
   This drawer slides in from the top.
   <sl-button slot="footer" variant="primary">Close</sl-button>
@@ -117,10 +112,9 @@ To make the drawer slide in from the top, set the `placement` attribute to `top`
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDrawer from '@shoelace-style/shoelace/dist/react/drawer';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -144,7 +138,7 @@ const App = () => {
 
 To make the drawer slide in from the bottom, set the `placement` attribute to `bottom`.
 
-```html:preview
+```html preview
 <sl-drawer label="Drawer" placement="bottom" class="drawer-placement-bottom">
   This drawer slides in from the bottom.
   <sl-button slot="footer" variant="primary">Close</sl-button>
@@ -162,10 +156,9 @@ To make the drawer slide in from the bottom, set the `placement` attribute to `b
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDrawer from '@shoelace-style/shoelace/dist/react/drawer';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -189,9 +182,9 @@ const App = () => {
 
 By default, drawers slide out of their [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport. To make a drawer slide out of a parent element, add the `contained` attribute to the drawer and apply `position: relative` to its parent.
 
-Unlike normal drawers, contained drawers are not modal. This means they do not show an overlay, they do not trap focus, and they are not dismissible with [[Escape]]. This is intentional to allow users to interact with elements outside of the drawer.
+Unlike normal drawers, contained drawers are not modal. This means they do not show an overlay, they do not trap focus, and they are not dismissible with <kbd>Escape</kbd>. This is intentional to allow users to interact with elements outside of the drawer.
 
-```html:preview
+```html preview
 <div
   style="position: relative; border: solid 2px var(--sl-panel-border-color); height: 300px; padding: 1rem; margin-bottom: 1rem;"
 >
@@ -215,12 +208,9 @@ Unlike normal drawers, contained drawers are not modal. This means they do not s
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDrawer from '@shoelace-style/shoelace/dist/react/drawer';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -259,13 +249,11 @@ const App = () => {
 };
 ```
 
-{% endraw %}
-
 ### Custom Size
 
 Use the `--size` custom property to set the drawer's size. This will be applied to the drawer's width or height depending on its `placement`.
 
-```html:preview
+```html preview
 <sl-drawer label="Drawer" class="drawer-custom-size" style="--size: 50vw;">
   This drawer is always 50% of the viewport.
   <sl-button slot="footer" variant="primary">Close</sl-button>
@@ -283,12 +271,9 @@ Use the `--size` custom property to set the drawer's size. This will be applied
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDrawer from '@shoelace-style/shoelace/dist/react/drawer';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -308,13 +293,11 @@ const App = () => {
 };
 ```
 
-{% endraw %}
-
 ### Scrolling
 
 By design, a drawer's height will never exceed 100% of its container. As such, drawers will not scroll with the page to ensure the header and footer are always accessible to the user.
 
-```html:preview
+```html preview
 <sl-drawer label="Drawer" class="drawer-scrolling">
   <div style="height: 150vh; border: dashed 2px var(--sl-color-neutral-200); padding: 0 1rem;">
     <p>Scroll down and give it a try! 👇</p>
@@ -334,12 +317,9 @@ By design, a drawer's height will never exceed 100% of its container. As such, d
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDrawer from '@shoelace-style/shoelace/dist/react/drawer';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -367,13 +347,11 @@ const App = () => {
 };
 ```
 
-{% endraw %}
-
 ### Header Actions
 
 The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/components/icon-button) if needed.
 
-```html:preview
+```html preview
 <sl-drawer label="Drawer" class="drawer-header-actions">
   <sl-icon-button class="new-window" slot="header-actions" name="box-arrow-up-right"></sl-icon-button>
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
@@ -394,11 +372,9 @@ The header shows a functional close button by default. You can use the `header-a
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDrawer from '@shoelace-style/shoelace/dist/react/drawer';
-import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';
+import { SlButton, SlDrawer, SlIconButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -421,13 +397,13 @@ const App = () => {
 
 ### Preventing the Drawer from Closing
 
-By default, drawers will close when the user clicks the close button, clicks the overlay, or presses the [[Escape]] key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.
+By default, drawers will close when the user clicks the close button, clicks the overlay, or presses the <kbd>Escape</kbd> key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.
 
 To keep the drawer open in such cases, you can cancel the `sl-request-close` event. When canceled, the drawer will remain open and pulse briefly to draw the user's attention to it.
 
-You can use `event.detail.source` to determine what triggered the request to close. This example prevents the drawer from closing when the overlay is clicked, but allows the close button or [[Escape]] to dismiss it.
+You can use `event.detail.source` to determine what triggered the request to close. This example prevents the drawer from closing when the overlay is clicked, but allows the close button or <kbd>Escape</kbd> to dismiss it.
 
-```html:preview
+```html preview
 <sl-drawer label="Drawer" class="drawer-deny-close">
   This drawer will not close when you click on the overlay.
   <sl-button slot="footer" variant="primary">Close</sl-button>
@@ -452,10 +428,9 @@ You can use `event.detail.source` to determine what triggered the request to clo
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDrawer from '@shoelace-style/shoelace/dist/react/drawer';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -486,7 +461,7 @@ const App = () => {
 
 By default, the drawer's panel will gain focus when opened. This allows a subsequent tab press to focus on the first tabbable element in the drawer. If you want a different element to have focus, add the `autofocus` attribute to it as shown below.
 
-```html:preview
+```html preview
 <sl-drawer label="Drawer" class="drawer-focus">
   <sl-input autofocus placeholder="I will have focus when the drawer is opened"></sl-input>
   <sl-button slot="footer" variant="primary">Close</sl-button>
@@ -505,11 +480,9 @@ By default, the drawer's panel will gain focus when opened. This allows a subseq
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDrawer from '@shoelace-style/shoelace/dist/react/drawer';
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+import { SlButton, SlDrawer, SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -529,6 +502,5 @@ const App = () => {
 };
 ```
 
-:::tip
-You can further customize initial focus behavior by canceling the `sl-initial-focus` event and setting focus yourself inside the event handler.
-:::
+?> You can further customize initial focus behavior by canceling the `sl-initial-focus` event and setting focus yourself inside the event handler.
+[component-metadata:sl-drawer]

docs/components/dropdown.md

@@ -1,15 +1,12 @@
----
-meta:
-  title: Dropdown
-  description: 'Dropdowns expose additional content that "drops down" in a panel.'
-layout: component
----
+# Dropdown
+
+[component-header:sl-dropdown]
 
 Dropdowns consist of a trigger and a panel. By default, activating the trigger will expose the panel and interacting outside of the panel will close it.
 
-Dropdowns are designed to work well with [menus](/components/menu) to provide a list of options the user can select from. However, dropdowns can also be used in lower-level applications (e.g. [color picker](/components/color-picker)). The API gives you complete control over showing, hiding, and positioning the panel.
+Dropdowns are designed to work well with [menus](/components/menu) to provide a list of options the user can select from. However, dropdowns can also be used in lower-level applications (e.g. [color picker](/components/color-picker) and [select](/components/select)). The API gives you complete control over showing, hiding, and positioning the panel.
 
-```html:preview
+```html preview
 <sl-dropdown>
   <sl-button slot="trigger" caret>Dropdown</sl-button>
   <sl-menu>
@@ -32,13 +29,8 @@ Dropdowns are designed to work well with [menus](/components/menu) to provide a
 </sl-dropdown>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlDropdown from '@shoelace-style/shoelace/dist/react/dropdown';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlButton, SlDivider, SlDropdown, SlIcon, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlDropdown>
@@ -74,7 +66,7 @@ const App = () => (
 
 When dropdowns are used with [menus](/components/menu), you can listen for the [`sl-select`](/components/menu#events) event to determine which menu item was selected. The menu item element will be exposed in `event.detail.item`. You can set `value` props to make it easier to identify commands.
 
-```html:preview
+```html preview
 <div class="dropdown-selection">
   <sl-dropdown>
     <sl-button slot="trigger" caret>Edit</sl-button>
@@ -97,11 +89,8 @@ When dropdowns are used with [menus](/components/menu), you can listen for the [
 </script>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDropdown from '@shoelace-style/shoelace/dist/react/dropdown';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlButton, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   function handleSelect(event) {
@@ -126,7 +115,7 @@ const App = () => {
 
 Alternatively, you can listen for the `click` event on individual menu items. Note that, using this approach, disabled menu items will still emit a `click` event.
 
-```html:preview
+```html preview
 <div class="dropdown-selection-alt">
   <sl-dropdown>
     <sl-button slot="trigger" caret>Edit</sl-button>
@@ -150,11 +139,8 @@ Alternatively, you can listen for the `click` event on individual menu items. No
 </script>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDropdown from '@shoelace-style/shoelace/dist/react/dropdown';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlButton, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   function handleCut() {
@@ -188,7 +174,7 @@ const App = () => {
 
 The preferred placement of the dropdown can be set with the `placement` attribute. Note that the actual position may vary to ensure the panel remains in the viewport.
 
-```html:preview
+```html preview
 <sl-dropdown placement="top-start">
   <sl-button slot="trigger" caret>Edit</sl-button>
   <sl-menu>
@@ -202,12 +188,8 @@ The preferred placement of the dropdown can be set with the `placement` attribut
 </sl-dropdown>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlDropdown from '@shoelace-style/shoelace/dist/react/dropdown';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlButton, SlDivider, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlDropdown placement="top-start">
@@ -230,7 +212,7 @@ const App = () => (
 
 The distance from the panel to the trigger can be customized using the `distance` attribute. This value is specified in pixels.
 
-```html:preview
+```html preview
 <sl-dropdown distance="30">
   <sl-button slot="trigger" caret>Edit</sl-button>
   <sl-menu>
@@ -244,12 +226,8 @@ The distance from the panel to the trigger can be customized using the `distance
 </sl-dropdown>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlDropdown from '@shoelace-style/shoelace/dist/react/dropdown';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlButton, SlDivider, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlDropdown distance={30}>
@@ -272,7 +250,7 @@ const App = () => (
 
 The offset of the panel along the trigger can be customized using the `skidding` attribute. This value is specified in pixels.
 
-```html:preview
+```html preview
 <sl-dropdown skidding="30">
   <sl-button slot="trigger" caret>Edit</sl-button>
   <sl-menu>
@@ -286,12 +264,8 @@ The offset of the panel along the trigger can be customized using the `skidding`
 </sl-dropdown>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlDropdown from '@shoelace-style/shoelace/dist/react/dropdown';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlButton, SlDivider, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlDropdown skidding={30}>
@@ -310,101 +284,11 @@ const App = () => (
 );
 ```
 
-### Submenus
-
-To create a submenu, nest an `<sl-menu slot="submenu">` element in a [menu item](/components/menu-item).
-
-```html:preview
-<sl-dropdown>
-  <sl-button slot="trigger" caret>Edit</sl-button>
-
-  <sl-menu style="max-width: 200px;">
-    <sl-menu-item value="undo">Undo</sl-menu-item>
-    <sl-menu-item value="redo">Redo</sl-menu-item>
-    <sl-divider></sl-divider>
-    <sl-menu-item value="cut">Cut</sl-menu-item>
-    <sl-menu-item value="copy">Copy</sl-menu-item>
-    <sl-menu-item value="paste">Paste</sl-menu-item>
-    <sl-divider></sl-divider>
-    <sl-menu-item>
-      Find
-      <sl-menu slot="submenu">
-        <sl-menu-item value="find">Find…</sl-menu-item>
-        <sl-menu-item value="find-previous">Find Next</sl-menu-item>
-        <sl-menu-item value="find-next">Find Previous</sl-menu-item>
-      </sl-menu>
-    </sl-menu-item>
-    <sl-menu-item>
-      Transformations
-      <sl-menu slot="submenu">
-        <sl-menu-item value="uppercase">Make uppercase</sl-menu-item>
-        <sl-menu-item value="lowercase">Make lowercase</sl-menu-item>
-        <sl-menu-item value="capitalize">Capitalize</sl-menu-item>
-      </sl-menu>
-    </sl-menu-item>
-  </sl-menu>
-</sl-dropdown>
-```
-
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlDropdown from '@shoelace-style/shoelace/dist/react/dropdown';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
-
-const css = `
-  .dropdown-hoist {
-    border: solid 2px var(--sl-panel-border-color);
-    padding: var(--sl-spacing-medium);
-    overflow: hidden;
-  }
-`;
-
-const App = () => (
-  <>
-    <SlDropdown>
-      <SlButton slot="trigger" caret>Edit</SlButton>
-
-      <SlMenu style="max-width: 200px;">
-        <SlMenuItem value="undo">Undo</SlMenuItem>
-        <SlMenuItem value="redo">Redo</SlMenuItem>
-        <SlDivider />
-        <SlMenuItem value="cut">Cut</SlMenuItem>
-        <SlMenuItem value="copy">Copy</SlMenuItem>
-        <SlMenuItem value="paste">Paste</SlMenuItem>
-        <SlDivider />
-        <SlMenuItem>
-          Find
-          <SlMenu slot="submenu">
-            <SlMenuItem value="find">Find…</SlMenuItem>
-            <SlMenuItem value="find-previous">Find Next</SlMenuItem>
-            <SlMenuItem value="find-next">Find Previous</SlMenuItem>
-          </SlMenu>
-        </SlMenuItem>
-        <SlMenuItem>
-          Transformations
-          <SlMenu slot="submenu">
-            <SlMenuItem value="uppercase">Make uppercase</SlMenuItem>
-            <SlMenuItem value="lowercase">Make lowercase</SlMenuItem>
-            <SlMenuItem value="capitalize">Capitalize</SlMenuItem>
-          </SlMenu>
-        </SlMenuItem>
-      </SlMenu>
-    </SlDropdown>
-  </>
-);
-```
-
-:::warning
-As a UX best practice, avoid using more than one level of submenu when possible.
-:::
-
 ### Hoisting
 
-Dropdown panels will be clipped if they're inside a container that has `overflow: auto|hidden`. The `hoist` attribute forces the panel to use a fixed positioning strategy, allowing it to break out of the container. In this case, the panel will be positioned relative to its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
+Dropdown panels will be clipped if they're inside a container that has `overflow: auto|hidden`. The `hoist` attribute forces the panel to use a fixed positioning strategy, allowing it to break out of the container. In this case, the panel will be positioned relative to its containing block, which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
 
-```html:preview
+```html preview
 <div class="dropdown-hoist">
   <sl-dropdown>
     <sl-button slot="trigger" caret>No Hoist</sl-button>
@@ -435,12 +319,8 @@ Dropdown panels will be clipped if they're inside a container that has `overflow
 </style>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlDropdown from '@shoelace-style/shoelace/dist/react/dropdown';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlButton, SlDivider, SlDropdown, SlIcon, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .dropdown-hoist {
@@ -480,3 +360,5 @@ const App = () => (
   </>
 );
 ```
+
+[component-metadata:sl-dropdown]

docs/components/format-bytes.md

@@ -1,11 +1,8 @@
----
-meta:
-  title: Format Bytes
-  description: Formats a number as a human readable bytes value.
-layout: component
----
+# Format Bytes
 
-```html:preview
+[component-header:sl-format-bytes]
+
+```html preview
 <div class="format-bytes-overview">
   The file is <sl-format-bytes value="1000"></sl-format-bytes> in size. <br /><br />
   <sl-input type="number" value="1000" label="Number to Format" style="max-width: 180px;"></sl-input>
@@ -20,13 +17,9 @@ layout: component
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlFormatBytes from '@shoelace-style/shoelace/dist/react/format-bytes';
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+import { SlButton, SlFormatBytes, SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [value, setValue] = useState(1000);
@@ -48,23 +41,21 @@ const App = () => {
 };
 ```
 
-{% endraw %}
-
 ## Examples
 
 ### Formatting Bytes
 
 Set the `value` attribute to a number to get the value in bytes.
 
-```html:preview
+```html preview
 <sl-format-bytes value="12"></sl-format-bytes><br />
 <sl-format-bytes value="1200"></sl-format-bytes><br />
 <sl-format-bytes value="1200000"></sl-format-bytes><br />
 <sl-format-bytes value="1200000000"></sl-format-bytes>
 ```
 
-```jsx:react
-import SlFormatBytes from '@shoelace-style/shoelace/dist/react/format-bytes';
+```jsx react
+import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -83,15 +74,15 @@ const App = () => (
 
 To get the value in bits, set the `unit` attribute to `bit`.
 
-```html:preview
+```html preview
 <sl-format-bytes value="12" unit="bit"></sl-format-bytes><br />
 <sl-format-bytes value="1200" unit="bit"></sl-format-bytes><br />
 <sl-format-bytes value="1200000" unit="bit"></sl-format-bytes><br />
 <sl-format-bytes value="1200000000" unit="bit"></sl-format-bytes>
 ```
 
-```jsx:react
-import SlFormatBytes from '@shoelace-style/shoelace/dist/react/format-bytes';
+```jsx react
+import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -110,15 +101,15 @@ const App = () => (
 
 Use the `lang` attribute to set the number formatting locale.
 
-```html:preview
+```html preview
 <sl-format-bytes value="12" lang="de"></sl-format-bytes><br />
 <sl-format-bytes value="1200" lang="de"></sl-format-bytes><br />
 <sl-format-bytes value="1200000" lang="de"></sl-format-bytes><br />
 <sl-format-bytes value="1200000000" lang="de"></sl-format-bytes>
 ```
 
-```jsx:react
-import SlFormatBytes from '@shoelace-style/shoelace/dist/react/format-bytes';
+```jsx react
+import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -132,3 +123,5 @@ const App = () => (
   </>
 );
 ```
+
+[component-metadata:sl-format-bytes]

docs/components/format-date.md

@@ -1,28 +1,23 @@
----
-meta:
-  title: Format Date
-  description: Formats a date/time using the specified locale and options.
-layout: component
----
+# Format Date
+
+[component-header:sl-format-date]
 
 Localization is handled by the browser's [`Intl.DateTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). No language packs are required.
 
-```html:preview
+```html preview
 <!-- Shoelace 2 release date 🎉 -->
 <sl-format-date date="2020-07-15T09:17:00-04:00"></sl-format-date>
 ```
 
-```jsx:react
-import SlFormatDate from '@shoelace-style/shoelace/dist/react/format-date';
+```jsx react
+import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlFormatDate date="2020-07-15T09:17:00-04:00" />;
 ```
 
 The `date` attribute determines the date/time to use when formatting. It must be a string that [`Date.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse) can interpret or a [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object set via JavaScript. If omitted, the current date/time will be assumed.
 
-:::tip
-When using strings, avoid ambiguous dates such as `03/04/2020` which can be interpreted as March 4 or April 3 depending on the user's browser and locale. Instead, always use a valid [ISO 8601 date time string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse#Date_Time_String_Format) to ensure the date will be parsed properly by all clients.
-:::
+?> When using strings, avoid ambiguous dates such as `03/04/2020` which can be interpreted as March 4 or April 3 depending on the user's browser and locale. Instead, always use a valid [ISO 8601 date time string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse#Date_Time_String_Format) to ensure the date will be parsed properly by all clients.
 
 ## Examples
 
@@ -30,7 +25,7 @@ When using strings, avoid ambiguous dates such as `03/04/2020` which can be inte
 
 Formatting options are based on those found in the [`Intl.DateTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). When formatting options are provided, the date/time will be formatted according to those values. When no formatting options are provided, a localized, numeric date will be displayed instead.
 
-```html:preview
+```html preview
 <!-- Human-readable date -->
 <sl-format-date month="long" day="numeric" year="numeric"></sl-format-date><br />
 
@@ -50,8 +45,8 @@ Formatting options are based on those found in the [`Intl.DateTimeFormat` API](h
 <sl-format-date></sl-format-date>
 ```
 
-```jsx:react
-import SlFormatDate from '@shoelace-style/shoelace/dist/react/format-date';
+```jsx react
+import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -85,13 +80,13 @@ const App = () => (
 
 By default, the browser will determine whether to use 12-hour or 24-hour time. To force one or the other, set the `hour-format` attribute to `12` or `24`.
 
-```html:preview
+```html preview
 <sl-format-date hour="numeric" minute="numeric" hour-format="12"></sl-format-date><br />
 <sl-format-date hour="numeric" minute="numeric" hour-format="24"></sl-format-date>
 ```
 
-```jsx:react
-import SlFormatDate from '@shoelace-style/shoelace/dist/react/format-date';
+```jsx react
+import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -106,14 +101,14 @@ const App = () => (
 
 Use the `lang` attribute to set the date/time formatting locale.
 
-```html:preview
+```html preview
 English: <sl-format-date lang="en"></sl-format-date><br />
 French: <sl-format-date lang="fr"></sl-format-date><br />
 Russian: <sl-format-date lang="ru"></sl-format-date>
 ```
 
-```jsx:react
-import SlFormatDate from '@shoelace-style/shoelace/dist/react/format-date';
+```jsx react
+import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -125,3 +120,5 @@ const App = () => (
   </>
 );
 ```
+
+[component-metadata:sl-format-date]

docs/components/format-number.md

@@ -1,13 +1,10 @@
----
-meta:
-  title: Format Number
-  description: Formats a number using the specified locale and options.
-layout: component
----
+# Format Number
+
+[component-header:sl-format-number]
 
 Localization is handled by the browser's [`Intl.NumberFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat). No language packs are required.
 
-```html:preview
+```html preview
 <div class="format-number-overview">
   <sl-format-number value="1000"></sl-format-number>
   <br /><br />
@@ -23,12 +20,9 @@ Localization is handled by the browser's [`Intl.NumberFormat` API](https://devel
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlFormatNumber from '@shoelace-style/shoelace/dist/react/format-number';
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+import { SlFormatNumber, SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [value, setValue] = useState(1000);
@@ -50,15 +44,13 @@ const App = () => {
 };
 ```
 
-{% endraw %}
-
 ## Examples
 
 ### Percentages
 
 To get the value as a percent, set the `type` attribute to `percent`.
 
-```html:preview
+```html preview
 <sl-format-number type="percent" value="0"></sl-format-number><br />
 <sl-format-number type="percent" value="0.25"></sl-format-number><br />
 <sl-format-number type="percent" value="0.50"></sl-format-number><br />
@@ -66,8 +58,8 @@ To get the value as a percent, set the `type` attribute to `percent`.
 <sl-format-number type="percent" value="1"></sl-format-number>
 ```
 
-```jsx:react
-import SlFormatNumber from '@shoelace-style/shoelace/dist/react/format-number';
+```jsx react
+import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -88,14 +80,14 @@ const App = () => (
 
 Use the `lang` attribute to set the number formatting locale.
 
-```html:preview
+```html preview
 English: <sl-format-number value="2000" lang="en" minimum-fraction-digits="2"></sl-format-number><br />
 German: <sl-format-number value="2000" lang="de" minimum-fraction-digits="2"></sl-format-number><br />
 Russian: <sl-format-number value="2000" lang="ru" minimum-fraction-digits="2"></sl-format-number>
 ```
 
-```jsx:react
-import SlFormatNumber from '@shoelace-style/shoelace/dist/react/format-number';
+```jsx react
+import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -112,7 +104,7 @@ const App = () => (
 
 To format a number as a monetary value, set the `type` attribute to `currency` and set the `currency` attribute to the desired ISO 4217 currency code. You should also specify `lang` to ensure the the number is formatted correctly for the target locale.
 
-```html:preview
+```html preview
 <sl-format-number type="currency" currency="USD" value="2000" lang="en-US"></sl-format-number><br />
 <sl-format-number type="currency" currency="GBP" value="2000" lang="en-GB"></sl-format-number><br />
 <sl-format-number type="currency" currency="EUR" value="2000" lang="de"></sl-format-number><br />
@@ -120,8 +112,8 @@ To format a number as a monetary value, set the `type` attribute to `currency` a
 <sl-format-number type="currency" currency="CNY" value="2000" lang="zh-cn"></sl-format-number>
 ```
 
-```jsx:react
-import SlFormatNumber from '@shoelace-style/shoelace/dist/react/format-number';
+```jsx react
+import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -137,3 +129,5 @@ const App = () => (
   </>
 );
 ```
+
+[component-metadata:sl-format-number]

docs/components/icon-button.md

@@ -1,18 +1,15 @@
----
-meta:
-  title: Icon Button
-  description: Icons buttons are simple, icon-only buttons that can be used for actions and in toolbars.
-layout: component
----
+# Icon Button
+
+[component-header:sl-icon-button]
 
 For a full list of icons that come bundled with Shoelace, refer to the [icon component](/components/icon).
 
-```html:preview
+```html preview
 <sl-icon-button name="gear" label="Settings"></sl-icon-button>
 ```
 
-```jsx:react
-import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';
+```jsx react
+import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlIconButton name="gear" label="Settings" />;
 ```
@@ -23,16 +20,14 @@ const App = () => <SlIconButton name="gear" label="Settings" />;
 
 Icon buttons inherit their parent element's `font-size`.
 
-```html:preview
+```html preview
 <sl-icon-button name="pencil" label="Edit" style="font-size: 1.5rem;"></sl-icon-button>
 <sl-icon-button name="pencil" label="Edit" style="font-size: 2rem;"></sl-icon-button>
 <sl-icon-button name="pencil" label="Edit" style="font-size: 2.5rem;"></sl-icon-button>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';
+```jsx react
+import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -43,13 +38,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Colors
 
 Icon buttons are designed to have a uniform appearance, so their color is not inherited. However, you can still customize them by styling the `base` part.
 
-```html:preview
+```html preview
 <div class="icon-button-color">
   <sl-icon-button name="type-bold" label="Bold"></sl-icon-button>
   <sl-icon-button name="type-italic" label="Italic"></sl-icon-button>
@@ -72,8 +65,8 @@ Icon buttons are designed to have a uniform appearance, so their color is not in
 </style>
 ```
 
-```jsx:react
-import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';
+```jsx react
+import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .icon-button-color sl-icon-button::part(base) {
@@ -107,12 +100,12 @@ const App = () => (
 
 Use the `href` attribute to convert the button to a link.
 
-```html:preview
+```html preview
 <sl-icon-button name="gear" label="Settings" href="https://example.com" target="_blank"></sl-icon-button>
 ```
 
-```jsx:react
-import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';
+```jsx react
+import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlIconButton name="gear" label="Settings" href="https://example.com" target="_blank" />;
 ```
@@ -121,15 +114,14 @@ const App = () => <SlIconButton name="gear" label="Settings" href="https://examp
 
 Wrap a tooltip around an icon button to provide contextual information to the user.
 
-```html:preview
+```html preview
 <sl-tooltip content="Settings">
   <sl-icon-button name="gear" label="Settings"></sl-icon-button>
 </sl-tooltip>
 ```
 
-```jsx:react
-import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';
-import SlTooltip from '@shoelace-style/shoelace/dist/react/tooltip';
+```jsx react
+import { SlIconButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTooltip content="Settings">
@@ -142,12 +134,14 @@ const App = () => (
 
 Use the `disabled` attribute to disable the icon button.
 
-```html:preview
+```html preview
 <sl-icon-button name="gear" label="Settings" disabled></sl-icon-button>
 ```
 
-```jsx:react
-import SlIconButton from '@shoelace-style/shoelace/dist/react/icon-button';
+```jsx react
+import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlIconButton name="gear" label="Settings" disabled />;
 ```
+
+[component-metadata:sl-icon-button]

docs/components/icon.md

@@ -1,15 +1,10 @@
----
-meta:
-  title: Icon
-  description: Icons are symbols that can be used to represent various options within an application.
-layout: component
----
+# Icon
+
+[component-header:sl-icon]
 
 Shoelace comes bundled with over 1,500 icons courtesy of the [Bootstrap Icons](https://icons.getbootstrap.com/) project. These icons are part of the `default` icon library. If you prefer, you can register [custom icon libraries](#icon-libraries) as well.
 
-:::tip
-Depending on how you're loading Shoelace, you may need to copy icon assets and/or [set the base path](/getting-started/installation/#setting-the-base-path) so Shoelace knows where to load them from. Otherwise, icons may not appear and you'll see 404 Not Found errors in the dev console.
-:::
+?> Depending on how you're loading Shoelace, you may need to copy icon assets and/or [set the base path](getting-started/installation#setting-the-base-path) so Shoelace knows where to load them from. Otherwise, icons may not appear and you'll see 404 Not Found errors in the dev console.
 
 ## Default Icons
 
@@ -40,7 +35,7 @@ All available icons in the `default` icon library are shown below. Click or tap
 
 Icons inherit their color from the current text color. Thus, you can set the `color` property on the `<sl-icon>` element or an ancestor to change the color.
 
-```html:preview
+```html preview
 <div style="color: #4a90e2;">
   <sl-icon name="exclamation-triangle"></sl-icon>
   <sl-icon name="archive"></sl-icon>
@@ -67,10 +62,8 @@ Icons inherit their color from the current text color. Thus, you can set the `co
 </div>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -102,13 +95,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Sizing
 
 Icons are sized relative to the current font size. To change their size, set the `font-size` property on the icon itself or on a parent element as shown below.
 
-```html:preview
+```html preview
 <div style="font-size: 32px;">
   <sl-icon name="exclamation-triangle"></sl-icon>
   <sl-icon name="archive"></sl-icon>
@@ -129,10 +120,8 @@ Icons are sized relative to the current font size. To change their size, set the
 </div>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <div style={{ fontSize: '32px' }}>
@@ -156,18 +145,16 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Labels
 
 For non-decorative icons, use the `label` attribute to announce it to assistive devices.
 
-```html:preview
+```html preview
 <sl-icon name="star-fill" label="Add to favorites"></sl-icon>
 ```
 
-```jsx:react
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlIcon name="star-fill" label="Add to favorites" />;
 ```
@@ -176,20 +163,16 @@ const App = () => <SlIcon name="star-fill" label="Add to favorites" />;
 
 Custom icons can be loaded individually with the `src` attribute. Only SVGs on a local or CORS-enabled endpoint are supported. If you're using more than one custom icon, it might make sense to register a [custom icon library](#icon-libraries).
 
-```html:preview
+```html preview
 <sl-icon src="https://shoelace.style/assets/images/shoe.svg" style="font-size: 8rem;"></sl-icon>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlIcon src="https://shoelace.style/assets/images/shoe.svg" style={{ fontSize: '8rem' }}></SlIcon>;
 ```
 
-{% endraw %}
-
 ## Icon Libraries
 
 You can register additional icons to use with the `<sl-icon>` component through icon libraries. Icon files can exist locally or on a CORS-enabled endpoint (e.g. a CDN). There is no limit to how many icon libraries you can register and there is no cost associated with registering them, as individual icons are only requested when they're used.
@@ -230,7 +213,7 @@ This will register the [Boxicons](https://boxicons.com/) library using the jsDel
 
 Icons in this library are licensed under the [Creative Commons 4.0 License](https://github.com/atisawd/boxicons#license).
 
-```html:preview
+```html preview
 <script type="module">
   import { registerIconLibrary } from '/dist/utilities/icon-library.js';
 
@@ -275,7 +258,7 @@ This will register the [Lucide](https://lucide.dev/) icon library using the jsDe
 
 Icons in this library are licensed under the [MIT License](https://github.com/lucide-icons/lucide/blob/master/LICENSE).
 
-```html:preview
+```html preview
 <div style="font-size: 24px;">
   <sl-icon library="lucide" name="feather"></sl-icon>
   <sl-icon library="lucide" name="pie-chart"></sl-icon>
@@ -300,7 +283,7 @@ This will register the [Font Awesome Free](https://fontawesome.com/) library usi
 
 Icons in this library are licensed under the [Font Awesome Free License](https://github.com/FortAwesome/Font-Awesome/blob/master/LICENSE.txt). Some of the icons that appear on the Font Awesome website require a license and are therefore not available in the CDN.
 
-```html:preview
+```html preview
 <script type="module">
   import { registerIconLibrary } from '/dist/utilities/icon-library.js';
 
@@ -346,7 +329,7 @@ This will register the [Heroicons](https://heroicons.com/) library using the jsD
 
 Icons in this library are licensed under the [MIT License](https://github.com/tailwindlabs/heroicons/blob/master/LICENSE).
 
-```html:preview
+```html preview
 <script type="module">
   import { registerIconLibrary } from '/dist/utilities/icon-library.js';
 
@@ -371,7 +354,7 @@ This will register the [Iconoir](https://iconoir.com/) library using the jsDeliv
 
 Icons in this library are licensed under the [MIT License](https://github.com/lucaburgio/iconoir/blob/master/LICENSE).
 
-```html:preview
+```html preview
 <script type="module">
   import { registerIconLibrary } from '/dist/utilities/icon-library.js';
 
@@ -396,7 +379,7 @@ This will register the [Ionicons](https://ionicons.com/) library using the jsDel
 
 Icons in this library are licensed under the [MIT License](https://github.com/ionic-team/ionicons/blob/master/LICENSE).
 
-```html:preview
+```html preview
 <script type="module">
   import { registerIconLibrary } from '/dist/utilities/icon-library.js';
 
@@ -441,7 +424,7 @@ This will register the [Jam Icons](https://jam-icons.com/) library using the jsD
 
 Icons in this library are licensed under the [MIT License](https://github.com/michaelampr/jam/blob/master/LICENSE).
 
-```html:preview
+```html preview
 <script type="module">
   import { registerIconLibrary } from '/dist/utilities/icon-library.js';
 
@@ -474,7 +457,7 @@ This will register the [Material Icons](https://material.io/resources/icons/?sty
 
 Icons in this library are licensed under the [Apache 2.0 License](https://github.com/google/material-design-icons/blob/master/LICENSE).
 
-```html:preview
+```html preview
 <script type="module">
   import { registerIconLibrary } from '/dist/utilities/icon-library.js';
 
@@ -517,7 +500,7 @@ This will register the [Remix Icon](https://remixicon.com/) library using the js
 
 Icons in this library are licensed under the [Apache 2.0 License](https://github.com/Remix-Design/RemixIcon/blob/master/License).
 
-```html:preview
+```html preview
 <script type="module">
   import { registerIconLibrary } from '/dist/utilities/icon-library.js';
 
@@ -554,7 +537,7 @@ This will register the [Tabler Icons](https://tabler-icons.io/) library using th
 
 Icons in this library are licensed under the [MIT License](https://github.com/tabler/tabler-icons/blob/master/LICENSE).
 
-```html:preview
+```html preview
 <script type="module">
   import { registerIconLibrary } from '/dist/utilities/icon-library.js';
 
@@ -586,7 +569,7 @@ This will register the [Unicons](https://iconscout.com/unicons) library using th
 
 Icons in this library are licensed under the [Apache 2.0 License](https://github.com/Iconscout/unicons/blob/master/LICENSE). Some of the icons that appear on the Unicons website, particularly many of the solid variations, require a license and are therefore not available in the CDN.
 
-```html:preview
+```html preview
 <script type="module">
   import { registerIconLibrary } from '/dist/utilities/icon-library.js';
 
@@ -634,37 +617,6 @@ This example will load the same set of icons from the jsDelivr CDN instead of yo
 </script>
 ```
 
-#### Customize the default library to use SVG sprites
-
-To improve performance you can use a SVG sprites to avoid multiple trips for each SVG. The browser will load the sprite sheet once and then you reference the particular SVG within the sprite sheet using hash selector.
-
-As always, make sure to benchmark these changes. When using HTTP/2, it may in fact be more bandwidth-friendly to use multiple small requests instead of 1 large sprite sheet.
-
-:::danger
-When using sprite sheets, the `sl-load` and `sl-error` events will not fire.
-:::
-
-:::danger
-For security reasons, browsers may apply the same-origin policy on `<use>` elements located in the `<sl-icon>` shadow DOM and may refuse to load a cross-origin URL. There is currently no defined way to set a cross-origin policy for `<use>` elements. For this reason, sprite sheets should only be used if you're self-hosting them.
-:::
-
-```html:preview
-<script type="module">
-  import { registerIconLibrary } from '/dist/utilities/icon-library.js';
-
-  registerIconLibrary('sprite', {
-    resolver: name => `/assets/images/sprite.svg#${name}`,
-    mutator: svg => svg.setAttribute('fill', 'currentColor'),
-    spriteSheet: true
-  });
-</script>
-
-<div style="font-size: 24px;">
-  <sl-icon library="sprite" name="clock"></sl-icon>
-  <sl-icon library="sprite" name="speedometer"></sl-icon>
-</div>
-```
-
 ### Customizing the System Library
 
 The system library contains only the icons used internally by Shoelace components. Unlike the default icon library, the system library does not rely on physical assets. Instead, its icons are hard-coded as data URIs into the resolver to ensure their availability.
@@ -697,7 +649,7 @@ If you want to change the icons Shoelace uses internally, you can register an ic
   }
 
   fetch('/dist/assets/icons/icons.json')
-    .then(res => res.json())
+    .then(res => res.json())  
     .then(icons => {
       const container = document.querySelector('.icon-search');
       const input = container.querySelector('sl-input');
@@ -716,12 +668,12 @@ If you want to change the icons Shoelace uses internally, you can register an ic
         item.setAttribute('data-terms', [i.name, i.title, ...(i.tags || []), ...(i.categories || [])].join(' '));
         item.innerHTML = `
           <svg width="1em" height="1em" fill="currentColor">
-            <use href="/assets/images/sprite.svg#${i.name}"></use>
-          </svg>
+            <use xlink:href="/assets/icons/sprite.svg#${i.name}"></use>
+          </svg>      
         `;
         list.appendChild(item);
 
-        // Wrap it with a tooltip the first time the mouse lands on it. We do this instead of baking them into the DOM
+        // Wrap it with a tooltip the first time the mouse lands on it. We do this instead of baking them into the DOM 
         // to improve this page's performance. See: https://github.com/shoelace-style/shoelace/issues/1122
         item.addEventListener('mouseover', () => wrapWithTooltip(item), { once: true });
 
@@ -756,12 +708,12 @@ If you want to change the icons Shoelace uses internally, you can register an ic
       });
 
       // Sort by type and remember preference
-      const iconType = sessionStorage.getItem('sl-icon:type') || 'outline';
+      const iconType = localStorage.getItem('sl-icon:type') || 'outline';
       select.value = iconType;
       list.setAttribute('data-type', select.value);
       select.addEventListener('sl-change', () => {
         list.setAttribute('data-type', select.value);
-        sessionStorage.setItem('sl-icon:type', select.value);
+        localStorage.setItem('sl-icon:type', select.value);
       });
     });
 </script>
@@ -864,6 +816,8 @@ If you want to change the icons Shoelace uses internally, you can register an ic
   @media screen and (max-width: 500px) {
     .icon-list {
       grid-template-columns: repeat(4, 1fr);
-    }
+    }    
   }
 </style>
+
+[component-metadata:sl-icon]

docs/components/image-comparer.md

@@ -1,13 +1,10 @@
----
-meta:
-  title: Image Comparer
-  description: Compare visual differences between similar photos with a sliding panel.
-layout: component
----
+# Image Comparer
+
+[component-header:sl-image-comparer]
 
 For best results, use images that share the same dimensions. The slider can be controlled by dragging or pressing the left and right arrow keys. (Tip: press shift + arrows to move the slider in larger intervals, or home + end to jump to the beginning or end.)
 
-```html:preview
+```html preview
 <sl-image-comparer>
   <img
     slot="before"
@@ -22,8 +19,8 @@ For best results, use images that share the same dimensions. The slider can be c
 </sl-image-comparer>
 ```
 
-```jsx:react
-import SlImageComparer from '@shoelace-style/shoelace/dist/react/image-comparer';
+```jsx react
+import { SlImageComparer } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlImageComparer>
@@ -47,7 +44,7 @@ const App = () => (
 
 Use the `position` attribute to set the initial position of the slider. This is a percentage from `0` to `100`.
 
-```html:preview
+```html preview
 <sl-image-comparer position="25">
   <img
     slot="before"
@@ -62,8 +59,8 @@ Use the `position` attribute to set the initial position of the slider. This is
 </sl-image-comparer>
 ```
 
-```jsx:react
-import SlImageComparer from '@shoelace-style/shoelace/dist/react/image-comparer';
+```jsx react
+import { SlImageComparer } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlImageComparer position={25}>
@@ -80,3 +77,5 @@ const App = () => (
   </SlImageComparer>
 );
 ```
+
+[component-metadata:sl-image-comparer]

docs/components/include.md

@@ -1,20 +1,17 @@
----
-meta:
-  title: Include
-  description: Includes give you the power to embed external HTML files into the page.
-layout: component
----
+# Include
+
+[component-header:sl-include]
 
 Included files are asynchronously requested using `window.fetch()`. Requests are cached, so the same file can be included multiple times, but only one request will be made.
 
 The included content will be inserted into the `<sl-include>` element's default slot so it can be easily accessed and styled through the light DOM.
 
-```html:preview
+```html preview
 <sl-include src="https://shoelace.style/assets/examples/include.html"></sl-include>
 ```
 
-```jsx:react
-import SlInclude from '@shoelace-style/shoelace/dist/react/include';
+```jsx react
+import { SlInclude } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlInclude src="https://shoelace.style/assets/examples/include.html" />;
 ```
@@ -46,3 +43,5 @@ If the request fails, the `sl-error` event will be emitted. In this case, `event
   });
 </script>
 ```
+
+[component-metadata:sl-include]

docs/components/input.md

@@ -1,23 +1,18 @@
----
-meta:
-  title: Input
-  description: Inputs collect data from the user.
-layout: component
----
+# Input
 
-```html:preview
+[component-header:sl-input]
+
+```html preview
 <sl-input></sl-input>
 ```
 
-```jsx:react
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlInput />;
 ```
 
-:::tip
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
-:::
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
@@ -25,13 +20,12 @@ This component works with standard `<form>` elements. Please refer to the sectio
 
 Use the `label` attribute to give the input an accessible label. For labels that contain HTML, use the `label` slot instead.
 
-```html:preview
+```html preview
 <sl-input label="What is your name?"></sl-input>
 ```
 
-```jsx:react
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+```jsx react
+import { SlIcon, SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlInput label="What is your name?" />;
 ```
@@ -40,13 +34,12 @@ const App = () => <SlInput label="What is your name?" />;
 
 Add descriptive help text to an input with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
 
-```html:preview
+```html preview
 <sl-input label="Nickname" help-text="What would you like people to call you?"></sl-input>
 ```
 
-```jsx:react
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+```jsx react
+import { SlIcon, SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlInput label="Nickname" help-text="What would you like people to call you?" />;
 ```
@@ -55,12 +48,12 @@ const App = () => <SlInput label="Nickname" help-text="What would you like peopl
 
 Use the `placeholder` attribute to add a placeholder.
 
-```html:preview
+```html preview
 <sl-input placeholder="Type something"></sl-input>
 ```
 
-```jsx:react
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlInput placeholder="Type something" />;
 ```
@@ -69,12 +62,12 @@ const App = () => <SlInput placeholder="Type something" />;
 
 Add the `clearable` attribute to add a clear button when the input has content.
 
-```html:preview
+```html preview
 <sl-input placeholder="Clearable" clearable></sl-input>
 ```
 
-```jsx:react
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlInput placeholder="Clearable" clearable />;
 ```
@@ -83,12 +76,12 @@ const App = () => <SlInput placeholder="Clearable" clearable />;
 
 Add the `password-toggle` attribute to add a toggle button that will show the password when activated.
 
-```html:preview
+```html preview
 <sl-input type="password" placeholder="Password Toggle" password-toggle></sl-input>
 ```
 
-```jsx:react
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlInput type="password" placeholder="Password Toggle" size="medium" password-toggle />;
 ```
@@ -97,12 +90,12 @@ const App = () => <SlInput type="password" placeholder="Password Toggle" size="m
 
 Add the `filled` attribute to draw a filled input.
 
-```html:preview
+```html preview
 <sl-input placeholder="Type something" filled></sl-input>
 ```
 
-```jsx:react
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlInput placeholder="Type something" filled />;
 ```
@@ -111,12 +104,12 @@ const App = () => <SlInput placeholder="Type something" filled />;
 
 Use the `disabled` attribute to disable an input.
 
-```html:preview
+```html preview
 <sl-input placeholder="Disabled" disabled></sl-input>
 ```
 
-```jsx:react
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlInput placeholder="Disabled" disabled />;
 ```
@@ -125,7 +118,7 @@ const App = () => <SlInput placeholder="Disabled" disabled />;
 
 Use the `size` attribute to change an input's size.
 
-```html:preview
+```html preview
 <sl-input placeholder="Small" size="small"></sl-input>
 <br />
 <sl-input placeholder="Medium" size="medium"></sl-input>
@@ -133,8 +126,8 @@ Use the `size` attribute to change an input's size.
 <sl-input placeholder="Large" size="large"></sl-input>
 ```
 
-```jsx:react
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -151,7 +144,7 @@ const App = () => (
 
 Use the `pill` attribute to give inputs rounded edges.
 
-```html:preview
+```html preview
 <sl-input placeholder="Small" size="small" pill></sl-input>
 <br />
 <sl-input placeholder="Medium" size="medium" pill></sl-input>
@@ -159,8 +152,8 @@ Use the `pill` attribute to give inputs rounded edges.
 <sl-input placeholder="Large" size="large" pill></sl-input>
 ```
 
-```jsx:react
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -177,7 +170,7 @@ const App = () => (
 
 The `type` attribute controls the type of input the browser renders.
 
-```html:preview
+```html preview
 <sl-input type="email" placeholder="Email"></sl-input>
 <br />
 <sl-input type="number" placeholder="Number"></sl-input>
@@ -185,8 +178,8 @@ The `type` attribute controls the type of input the browser renders.
 <sl-input type="date" placeholder="Date"></sl-input>
 ```
 
-```jsx:react
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -203,7 +196,7 @@ const App = () => (
 
 Use the `prefix` and `suffix` slots to add icons.
 
-```html:preview
+```html preview
 <sl-input placeholder="Small" size="small">
   <sl-icon name="house" slot="prefix"></sl-icon>
   <sl-icon name="chat" slot="suffix"></sl-icon>
@@ -220,9 +213,8 @@ Use the `prefix` and `suffix` slots to add icons.
 </sl-input>
 ```
 
-```jsx:react
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+```jsx react
+import { SlIcon, SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -248,8 +240,8 @@ const App = () => (
 
 Use [CSS parts](#css-parts) to customize the way form controls are drawn. This example uses CSS grid to position the label to the left of the control, but the possible orientations are nearly endless. The same technique works for inputs, textareas, radio groups, and similar form controls.
 
-```html:preview
-<sl-input class="label-on-left" label="Name" help-text="Enter your name"></sl-input>
+```html preview
+<sl-input class="label-on-left" label="Name" help-text="Enter your name""></sl-input>
 <sl-input class="label-on-left" label="Email" type="email" help-text="Enter your email"></sl-input>
 <sl-textarea class="label-on-left" label="Bio" help-text="Tell us something about yourself"></sl-textarea>
 
@@ -279,3 +271,5 @@ Use [CSS parts](#css-parts) to customize the way form controls are drawn. This e
   }
 </style>
 ```
+
+[component-metadata:sl-input]

docs/components/menu-item.md

@@ -1,11 +1,8 @@
----
-meta:
-  title: Menu Item
-  description: Menu items provide options for the user to pick from in a menu.
-layout: component
----
+# Menu Item
 
-```html:preview
+[component-header:sl-menu-item]
+
+```html preview
 <sl-menu style="max-width: 200px;">
   <sl-menu-item>Option 1</sl-menu-item>
   <sl-menu-item>Option 2</sl-menu-item>
@@ -25,13 +22,8 @@ layout: component
 </sl-menu>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlDivider, SlIcon, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlMenu style={{ maxWidth: '200px' }}>
@@ -56,15 +48,13 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ## Examples
 
 ### Disabled
 
 Add the `disabled` attribute to disable the menu item so it cannot be selected.
 
-```html:preview
+```html preview
 <sl-menu style="max-width: 200px;">
   <sl-menu-item>Option 1</sl-menu-item>
   <sl-menu-item disabled>Option 2</sl-menu-item>
@@ -72,11 +62,8 @@ Add the `disabled` attribute to disable the menu item so it cannot be selected.
 </sl-menu>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlMenu style={{ maxWidth: '200px' }}>
@@ -87,13 +74,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Prefix & Suffix
 
 Add content to the start and end of menu items using the `prefix` and `suffix` slots.
 
-```html:preview
+```html preview
 <sl-menu style="max-width: 200px;">
   <sl-menu-item>
     <sl-icon slot="prefix" name="house"></sl-icon>
@@ -115,14 +100,8 @@ Add content to the start and end of menu items using the `prefix` and `suffix` s
 </sl-menu>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlBadge from '@shoelace-style/shoelace/dist/react/badge';
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlBadge, SlDivider, SlIcon, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlMenu style={{ maxWidth: '200px' }}>
@@ -149,15 +128,13 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Checkbox Menu Items
 
 Set the `type` attribute to `checkbox` to create a menu item that will toggle on and off when selected. You can use the `checked` attribute to set the initial state.
 
 Checkbox menu items are visually indistinguishable from regular menu items. Their ability to be toggled is primarily inferred from context, much like you'd find in the menu of a native app.
 
-```html:preview
+```html preview
 <sl-menu style="max-width: 200px;">
   <sl-menu-item type="checkbox">Autosave</sl-menu-item>
   <sl-menu-item type="checkbox" checked>Check Spelling</sl-menu-item>
@@ -165,11 +142,8 @@ Checkbox menu items are visually indistinguishable from regular menu items. Thei
 </sl-menu>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlMenu style={{ maxWidth: '200px' }}>
@@ -182,13 +156,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Value & Selection
 
 The `value` attribute can be used to assign a hidden value, such as a unique identifier, to a menu item. When an item is selected, the `sl-select` event will be emitted and a reference to the item will be available at `event.detail.item`. You can use this reference to access the selected item's value, its checked state, and more.
 
-```html:preview
+```html preview
 <sl-menu class="menu-value" style="max-width: 200px;">
   <sl-menu-item value="opt-1">Option 1</sl-menu-item>
   <sl-menu-item value="opt-2">Option 2</sl-menu-item>
@@ -215,11 +187,8 @@ The `value` attribute can be used to assign a hidden value, such as a unique ide
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   function handleSelect(event) {
@@ -242,4 +211,4 @@ const App = () => {
 };
 ```
 
-{% endraw %}
+[component-metadata:sl-menu-item]

docs/components/menu-label.md

@@ -1,11 +1,8 @@
----
-meta:
-  title: Menu Label
-  description: Menu labels are used to describe a group of menu items.
-layout: component
----
+# Menu Label
 
-```html:preview
+[component-header:sl-menu-label]
+
+```html preview
 <sl-menu style="max-width: 200px;">
   <sl-menu-label>Fruits</sl-menu-label>
   <sl-menu-item value="apple">Apple</sl-menu-item>
@@ -19,13 +16,8 @@ layout: component
 </sl-menu>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlMenu from '@shoelace-style/shoelace/dist/react/menu';
-import SlMenuLabel from '@shoelace-style/shoelace/dist/react/menu-label';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+```jsx react
+import { SlDivider, SlMenu, SlMenuLabel, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlMenu style={{ maxWidth: '200px' }}>
@@ -42,4 +34,4 @@ const App = () => (
 );
 ```
 
-{% endraw %}
+[component-metadata:sl-menu-label]

docs/components/menu.md

@@ -0,0 +1,37 @@
+# Menu
+
+[component-header:sl-menu]
+
+You can use [menu items](/components/menu-item), [menu labels](/components/menu-label), and [dividers](/components/divider) to compose a menu. Menus support keyboard interactions, including type-to-select an option.
+
+```html preview
+<sl-menu style="max-width: 200px;">
+  <sl-menu-item value="undo">Undo</sl-menu-item>
+  <sl-menu-item value="redo">Redo</sl-menu-item>
+  <sl-divider></sl-divider>
+  <sl-menu-item value="cut">Cut</sl-menu-item>
+  <sl-menu-item value="copy">Copy</sl-menu-item>
+  <sl-menu-item value="paste">Paste</sl-menu-item>
+  <sl-menu-item value="delete">Delete</sl-menu-item>
+</sl-menu>
+```
+
+```jsx react
+import { SlDivider, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlMenu style={{ maxWidth: '200px' }}>
+    <SlMenuItem value="undo">Undo</SlMenuItem>
+    <SlMenuItem value="redo">Redo</SlMenuItem>
+    <SlDivider />
+    <SlMenuItem value="cut">Cut</SlMenuItem>
+    <SlMenuItem value="copy">Copy</SlMenuItem>
+    <SlMenuItem value="paste">Paste</SlMenuItem>
+    <SlMenuItem value="delete">Delete</SlMenuItem>
+  </SlMenu>
+);
+```
+
+?> Menus are intended for system menus (dropdown menus, select menus, context menus, etc.). They should not be mistaken for navigation menus which serve a different purpose and have a different semantic meaning. If you're building navigation, use `<nav>` and `<a>` elements instead.
+
+[component-metadata:sl-menu]

docs/components/mutation-observer.md

@@ -1,13 +1,10 @@
----
-meta:
-  title: Mutation Observer
-  description: The Mutation Observer component offers a thin, declarative interface to the MutationObserver API.
-layout: component
----
+# Mutation Observer
+
+[component-header:sl-mutation-observer]
 
 The mutation observer will report changes to the content it wraps through the `sl-mutation` event. When emitted, a collection of [MutationRecord](https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord) objects will be attached to `event.detail` that contains information about how it changed.
 
-```html:preview
+```html preview
 <div class="mutation-overview">
   <sl-mutation-observer attr="variant">
     <sl-button variant="primary">Click to mutate</sl-button>
@@ -43,16 +40,15 @@ The mutation observer will report changes to the content it wraps through the `s
 </div>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlMutationObserver from '@shoelace-style/shoelace/dist/react/mutation-observer';
+import { SlButton, SlMutationObserver } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .resize-observer-overview div {
-    display: flex;
-    border: solid 2px var(--sl-input-border-color);
-    align-items: center;
+    display: flex; 
+    border: solid 2px var(--sl-input-border-color); 
+    align-items: center; 
     justify-content: center;
     text-align: center;
     padding: 4rem 2rem;
@@ -84,9 +80,7 @@ const App = () => {
 };
 ```
 
-:::tip
-When you create a mutation observer, you must indicate what changes it should respond to by including at least one of `attr`, `child-list`, or `char-data`. If you don't specify at least one of these attributes, no mutation events will be emitted.
-:::
+?> When you create a mutation observer, you must indicate what changes it should respond to by including at least one of `attr`, `child-list`, or `char-data`. If you don't specify at least one of these attributes, no mutation events will be emitted.
 
 ## Examples
 
@@ -94,7 +88,7 @@ When you create a mutation observer, you must indicate what changes it should re
 
 Use the `child-list` attribute to watch for new child elements that are added or removed.
 
-```html:preview
+```html preview
 <div class="mutation-child-list">
   <sl-mutation-observer child-list>
     <div class="buttons">
@@ -145,10 +139,9 @@ Use the `child-list` attribute to watch for new child elements that are added or
 </div>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlMutationObserver from '@shoelace-style/shoelace/dist/react/mutation-observer';
+import { SlButton, SlMutationObserver } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .mutation-child-list .buttons {
@@ -194,3 +187,5 @@ const App = () => {
   );
 };
 ```
+
+[component-metadata:sl-mutation-observer]

docs/components/option.md

@@ -1,11 +1,8 @@
----
-meta:
-  title: Option
-  description: Options define the selectable items within various form controls such as select.
-layout: component
----
+# Option
 
-```html:preview
+[component-header:sl-option]
+
+```html preview
 <sl-select label="Select one">
   <sl-option value="option-1">Option 1</sl-option>
   <sl-option value="option-2">Option 2</sl-option>
@@ -13,9 +10,8 @@ layout: component
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect>
@@ -32,7 +28,7 @@ const App = () => (
 
 Use the `disabled` attribute to disable an option and prevent it from being selected.
 
-```html:preview
+```html preview
 <sl-select label="Select one">
   <sl-option value="option-1">Option 1</sl-option>
   <sl-option value="option-2" disabled>Option 2</sl-option>
@@ -40,9 +36,8 @@ Use the `disabled` attribute to disable an option and prevent it from being sele
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect>
@@ -59,7 +54,7 @@ const App = () => (
 
 Add icons to the start and end of menu items using the `prefix` and `suffix` slots.
 
-```html:preview
+```html preview
 <sl-select label="Select one">
   <sl-option value="option-1">
     <sl-icon slot="prefix" name="envelope"></sl-icon>
@@ -80,3 +75,5 @@ Add icons to the start and end of menu items using the `prefix` and `suffix` slo
   </sl-option>
 </sl-select>
 ```
+
+[component-metadata:sl-option]

docs/components/popup.md

@@ -1,19 +1,14 @@
----
-meta:
-  title: Popup
-  description: 'Popup is a utility that lets you declaratively anchor "popup" containers to another element.'
-layout: component
----
+# Popup
+
+[component-header:sl-popup]
 
 This component's name is inspired by [`<popup>`](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/Popup/explainer.md). It uses [Floating UI](https://floating-ui.com/) under the hood to provide a well-tested, lightweight, and fully declarative positioning utility for tooltips, dropdowns, and more.
 
 Popup doesn't provide any styles — just positioning! The popup's preferred placement, distance, and skidding (offset) can be configured using attributes. An arrow that points to the anchor can be shown and customized to your liking. Additional positioning options are available and described in more detail below.
 
-:::warning
-Popup is a low-level utility built specifically for positioning elements. Do not mistake it for a [tooltip](/components/tooltip) or similar because _it does not facilitate an accessible experience!_ Almost every correct usage of `<sl-popup>` will involve building other components. It should rarely, if ever, occur directly in your HTML.
-:::
+!> Popup is a low-level utility built specifically for positioning elements. Do not mistake it for a [tooltip](/components/tooltip) or similar because _it does not facilitate an accessible experience!_ Almost every correct usage of `<sl-popup>` will involve building other components. It should rarely, if ever, occur directly in your HTML.
 
-```html:preview
+```html preview
 <div class="popup-overview">
   <sl-popup placement="top" active>
     <span slot="anchor"></span>
@@ -102,13 +97,9 @@ Popup is a low-level utility built specifically for positioning elements. Do not
 </style>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
+import { SlPopup, SlSelect, SlMenuItem, SlInput, SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .popup-overview sl-popup {
@@ -224,9 +215,7 @@ const App = () => {
 };
 ```
 
-:::tip
-A popup's anchor should not be styled with `display: contents` since the coordinates will not be eligible for calculation. However, if the anchor is a `<slot>` element, popup will use the first assigned element as the anchor. This behavior allows other components to pass anchors through more easily via composition.
-:::
+?> A popup's anchor should not be styled with `display: contents` since the coordinates will not be eligible for calculation. However, if the anchor is a `<slot>` element, popup will use the first assigned element as the anchor. This behavior allows other components to pass anchors through more easily via composition.
 
 ## Examples
 
@@ -234,7 +223,7 @@ A popup's anchor should not be styled with `display: contents` since the coordin
 
 Popups are inactive and hidden until the `active` attribute is applied. Removing the attribute will tear down all positioning logic and listeners, meaning you can have many idle popups on the page without affecting performance.
 
-```html:preview
+```html preview
 <div class="popup-active">
   <sl-popup placement="top" active>
     <span slot="anchor"></span>
@@ -271,10 +260,9 @@ Popups are inactive and hidden until the `active` attribute is applied. Removing
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
+import { SlPopup, SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .popup-active span[slot='anchor'] {
@@ -320,7 +308,7 @@ const App = () => {
 
 By default, anchors are slotted into the popup using the `anchor` slot. If your anchor needs to live outside of the popup, you can pass the anchor's `id` to the `anchor` attribute. Alternatively, you can pass an element reference to the `anchor` property to achieve the same effect without using an `id`.
 
-```html:preview
+```html preview
 <span id="external-anchor"></span>
 
 <sl-popup anchor="external-anchor" placement="top" active>
@@ -345,8 +333,8 @@ By default, anchors are slotted into the popup using the `anchor` slot. If your
 </style>
 ```
 
-```jsx:react
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
+```jsx react
+import { SlPopup } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   #external-anchor {
@@ -386,7 +374,7 @@ Use the `placement` attribute to tell the popup the preferred placement of the p
 
 Since placement is preferred when using `flip`, you can observe the popup's current placement when it's active by looking at the `data-current-placement` attribute. This attribute will update as the popup flips to find available space and it will be removed when the popup is deactivated.
 
-```html:preview
+```html preview
 <div class="popup-placement">
   <sl-popup placement="top" active>
     <span slot="anchor"></span>
@@ -439,11 +427,9 @@ Since placement is preferred when using `flip`, you can observe the popup's curr
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+import { SlPopup, SlSelect, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .popup-placement span[slot='anchor'] {
@@ -503,7 +489,7 @@ const App = () => {
 
 Use the `distance` attribute to change the distance between the popup and its anchor. A positive value will move the popup further away and a negative value will move it closer.
 
-```html:preview
+```html preview
 <div class="popup-distance">
   <sl-popup placement="top" distance="0" active>
     <span slot="anchor"></span>
@@ -543,10 +529,9 @@ Use the `distance` attribute to change the distance between the popup and its an
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+import { SlPopup, SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .popup-distance span[slot='anchor'] {
@@ -600,7 +585,7 @@ const App = () => {
 
 The `skidding` attribute is similar to `distance`, but instead allows you to offset the popup along the anchor's axis. Both positive and negative values are allowed.
 
-```html:preview
+```html preview
 <div class="popup-skidding">
   <sl-popup placement="top" skidding="0" active>
     <span slot="anchor"></span>
@@ -640,10 +625,9 @@ The `skidding` attribute is similar to `distance`, but instead allows you to off
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+import { SlPopup, SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .popup-skidding span[slot='anchor'] {
@@ -699,7 +683,7 @@ Add an arrow to your popup with the `arrow` attribute. It's usually a good idea
 
 By default, the arrow will be aligned as close to the center of the _anchor_ as possible, considering available space and `arrow-padding`. You can use the `arrow-placement` attribute to force the arrow to align to the start, end, or center of the _popup_ instead.
 
-```html:preview
+```html preview
 <div class="popup-arrow">
   <sl-popup placement="top" arrow arrow-placement="anchor" distance="8" active>
     <span slot="anchor"></span>
@@ -784,12 +768,9 @@ By default, the arrow will be aligned as close to the center of the _anchor_ as
 </div>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
+import { SlPopup, SlSelect, SlMenuItem, SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .popup-arrow sl-popup {
@@ -892,7 +873,7 @@ const App = () => {
 
 Use the `sync` attribute to make the popup the same width or height as the anchor element. This is useful for controls that need the popup to stay the same width or height as the trigger.
 
-```html:preview
+```html preview
 <div class="popup-sync">
   <sl-popup placement="top" sync="width" active>
     <span slot="anchor"></span>
@@ -940,11 +921,9 @@ Use the `sync` attribute to make the popup the same width or height as the ancho
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+import { SlPopup, SlSelect, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .popup-sync span[slot='anchor'] {
@@ -998,13 +977,13 @@ const App = () => {
 
 By default, the popup is positioned using an absolute positioning strategy. However, if your anchor is fixed or exists within a container that has `overflow: auto|hidden`, the popup risks being clipped. To work around this, you can use a fixed positioning strategy by setting the `strategy` attribute to `fixed`.
 
-The fixed positioning strategy reduces jumpiness when the anchor is fixed and allows the popup to break out containers that clip. When using this strategy, it's important to note that the content will be positioned relative to its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
+The fixed positioning strategy reduces jumpiness when the anchor is fixed and allows the popup to break out containers that clip. When using this strategy, it's important to note that the content will be positioned _relative to its containing block_, which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
 
 In this example, you can see how the popup breaks out of the overflow container when it's fixed. The fixed positioning strategy tends to be less performant than absolute, so avoid using it unnecessarily.
 
 Toggle the switch and scroll the container to see the difference.
 
-```html:preview
+```html preview
 <div class="popup-strategy">
   <div class="overflow">
     <sl-popup placement="top" strategy="fixed" active>
@@ -1053,10 +1032,9 @@ Toggle the switch and scroll the container to see the difference.
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
+import { SlPopup, SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .popup-strategy .overflow {
@@ -1116,7 +1094,7 @@ When the popup doesn't have enough room in its preferred placement, it can autom
 
 Scroll the container to see how the popup flips to prevent clipping.
 
-```html:preview
+```html preview
 <div class="popup-flip">
   <div class="overflow">
     <sl-popup placement="top" flip active>
@@ -1162,10 +1140,9 @@ Scroll the container to see how the popup flips to prevent clipping.
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
+import { SlPopup, SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .popup-flip .overflow {
@@ -1226,7 +1203,7 @@ If no fallback placement works, the final placement will be determined by `flip-
 
 Scroll the container to see how the popup changes it's fallback placement to prevent clipping.
 
-```html:preview
+```html preview
 <div class="popup-flip-fallbacks">
   <div class="overflow">
     <sl-popup placement="top" flip flip-fallback-placements="right bottom" flip-fallback-strategy="initial" active>
@@ -1261,8 +1238,8 @@ Scroll the container to see how the popup changes it's fallback placement to pre
 </style>
 ```
 
-```jsx:react
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
+```jsx react
+import { SlPopup } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .popup-flip-fallbacks .overflow {
@@ -1312,7 +1289,7 @@ When a popup is longer than its anchor, it risks being clipped by an overflowing
 
 Toggle the switch to see the difference.
 
-```html:preview
+```html preview
 <div class="popup-shift">
   <div class="overflow">
     <sl-popup placement="top" shift shift-padding="10" active>
@@ -1356,10 +1333,9 @@ Toggle the switch to see the difference.
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
+import { SlPopup, SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .popup-shift .overflow {
@@ -1416,7 +1392,7 @@ When using `auto-size`, one or both of `--auto-size-available-width` and `--auto
 
 Scroll the container to see the popup resize as its available space changes.
 
-```html:preview
+```html preview
 <div class="popup-auto-size">
   <div class="overflow">
     <sl-popup placement="top" auto-size="both" auto-size-padding="10" active>
@@ -1469,10 +1445,9 @@ Scroll the container to see the popup resize as its available space changes.
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
+import { SlPopup, SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .popup-auto-size .overflow {
@@ -1530,178 +1505,4 @@ const App = () => {
 };
 ```
 
-### Virtual Elements
-
-In most cases, popups are anchored to an actual element. Sometimes, it can be useful to anchor them to a non-element. To do this, you can pass a `VirtualElement` to the anchor property. A virtual element must contain a function called `getBoundingClientRect()` that returns a [`DOMRect`](https://developer.mozilla.org/en-US/docs/Web/API/DOMRect) object as shown below.
-
-```ts
-const virtualElement = {
-  getBoundingClientRect() {
-    // ...
-    return { width, height, x, y, top, left, right, bottom };
-  }
-};
-```
-
-This example anchors a popup to the mouse cursor using a virtual element. As such, a mouse is required to properly view it.
-
-```html:preview
-<div class="popup-virtual-element">
-  <sl-popup placement="right-start">
-    <div class="circle"></div>
-  </sl-popup>
-
-  <sl-switch>Highlight mouse cursor</sl-switch>
-</div>
-
-<script>
-  const container = document.querySelector('.popup-virtual-element');
-  const popup = container.querySelector('sl-popup');
-  const circle = container.querySelector('.circle');
-  const enabled = container.querySelector('sl-switch');
-  let clientX = 0;
-  let clientY = 0;
-
-  // Set the virtual element as a property
-  popup.anchor = {
-    getBoundingClientRect() {
-      return {
-        width: 0,
-        height: 0,
-        x: clientX,
-        y: clientY,
-        top: clientY,
-        left: clientX,
-        right: clientX,
-        bottom: clientY
-      };
-    }
-  };
-
-  // Only activate the popup when the switch is checked
-  enabled.addEventListener('sl-change', () => {
-    popup.active = enabled.checked;
-  });
-
-  // Listen for the mouse to move
-  document.addEventListener('mousemove', handleMouseMove);
-
-  // Update the virtual element as the mouse moves
-  function handleMouseMove(event) {
-    clientX = event.clientX;
-    clientY = event.clientY;
-
-    // Reposition the popup when the virtual anchor moves
-    if (popup.active) {
-      popup.reposition();
-    }
-  }
-</script>
-
-<style>
-  /* If you need to set a z-index, set it on the popup part like this */
-  .popup-virtual-element sl-popup::part(popup) {
-    z-index: 1000;
-    pointer-events: none;
-  }
-
-  .popup-virtual-element .circle {
-    width: 100px;
-    height: 100px;
-    border: solid 4px var(--sl-color-primary-600);
-    border-radius: 50%;
-    translate: -50px -50px;
-    animation: 1s virtual-cursor infinite;
-  }
-
-  @keyframes virtual-cursor {
-    0% { scale: 1; }
-    50% { scale: 1.1; }
-  }
-</style>
-```
-
-```jsx:react
-import { useRef, useState } from 'react';
-import SlPopup from '@shoelace-style/shoelace/dist/react/popup';
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
-
-const css = `
-  /* If you need to set a z-index, set it on the popup part like this */
-  .popup-virtual-element sl-popup::part(popup) {
-    z-index: 1000;
-    pointer-events: none;
-  }
-
-  .popup-virtual-element .circle {
-    width: 100px;
-    height: 100px;
-    border: solid 4px var(--sl-color-primary-600);
-    border-radius: 50%;
-    translate: -50px -50px;
-    animation: 1s virtual-cursor infinite;
-  }
-
-  @keyframes virtual-cursor {
-    0% { scale: 1; }
-    50% { scale: 1.1; }
-  }
-`;
-
-const App = () => {
-  const [enabled, setEnabled] = useState(false);
-  const [clientX, setClientX] = useState(0);
-  const [clientY, setClientY] = useState(0);
-  const popup = useRef(null);
-  const circle = useRef(null);
-  const virtualElement = {
-    getBoundingClientRect() {
-      return {
-        width: 0,
-        height: 0,
-        x: clientX,
-        y: clientY,
-        top: clientY,
-        left: clientX,
-        right: clientX,
-        bottom: clientY
-      };
-    }
-  };
-
-  // Listen for the mouse to move
-  document.addEventListener('mousemove', handleMouseMove);
-
-  // Update the virtual element as the mouse moves
-  function handleMouseMove(event) {
-    setClientX(event.clientX);
-    setClientY(event.clientY);
-
-    // Reposition the popup when the virtual anchor moves
-    if (popup.active) {
-      popup.current.reposition();
-    }
-  }
-
-  return (
-    <>
-      <div className="popup-virtual-element">
-        <SlPopup
-          ref={popup}
-          placement="right-start"
-          active={enabled}
-          anchor={virtualElement}
-        >
-          <div ref={circle} className="circle" />
-        </SlPopup>
-
-        <SlSwitch checked={enabled} onSlChange={event => setEnabled(event.target.checked)}>
-          Highlight mouse cursor
-        </SlSwitch>
-      </div>
-
-      <style>{css}</style>
-    </>
-  );
-};
-```
+[component-metadata:sl-popup]

docs/components/progress-bar.md

@@ -1,16 +1,13 @@
----
-meta:
-  title: Progress Bar
-  description: Progress bars are used to show the status of an ongoing operation.
-layout: component
----
+# Progress Bar
 
-```html:preview
+[component-header:sl-progress-bar]
+
+```html preview
 <sl-progress-bar value="50"></sl-progress-bar>
 ```
 
-```jsx:react
-import SlProgressBar from '@shoelace-style/shoelace/dist/react/progress-bar';
+```jsx react
+import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlProgressBar value={50} />;
 ```
@@ -21,12 +18,12 @@ const App = () => <SlProgressBar value={50} />;
 
 Use the `label` attribute to label the progress bar and tell assistive devices how to announce it.
 
-```html:preview
+```html preview
 <sl-progress-bar value="50" label="Upload progress"></sl-progress-bar>
 ```
 
-```jsx:react
-import SlProgressBar from '@shoelace-style/shoelace/dist/react/progress-bar';
+```jsx react
+import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlProgressBar value="50" label="Upload progress" />;
 ```
@@ -35,25 +32,21 @@ const App = () => <SlProgressBar value="50" label="Upload progress" />;
 
 Use the `--height` custom property to set the progress bar's height.
 
-```html:preview
+```html preview
 <sl-progress-bar value="50" style="--height: 6px;"></sl-progress-bar>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlProgressBar from '@shoelace-style/shoelace/dist/react/progress-bar';
+```jsx react
+import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlProgressBar value={50} style={{ '--height': '6px' }} />;
 ```
 
-{% endraw %}
-
 ### Showing Values
 
 Use the default slot to show a value.
 
-```html:preview
+```html preview
 <sl-progress-bar value="50" class="progress-bar-values">50%</sl-progress-bar>
 
 <br />
@@ -80,11 +73,9 @@ Use the default slot to show a value.
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlProgressBar from '@shoelace-style/shoelace/dist/react/progress-bar';
+import { SlButton, SlIcon, SlProgressBar } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [value, setValue] = useState(50);
@@ -118,12 +109,14 @@ const App = () => {
 
 The `indeterminate` attribute can be used to inform the user that the operation is pending, but its status cannot currently be determined. In this state, `value` is ignored and the label, if present, will not be shown.
 
-```html:preview
+```html preview
 <sl-progress-bar indeterminate></sl-progress-bar>
 ```
 
-```jsx:react
-import SlProgressBar from '@shoelace-style/shoelace/dist/react/progress-bar';
+```jsx react
+import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlProgressBar indeterminate />;
 ```
+
+[component-metadata:sl-progress-bar]

docs/components/progress-ring.md

@@ -1,16 +1,13 @@
----
-meta:
-  title: Progress Ring
-  description: Progress rings are used to show the progress of a determinate operation in a circular fashion.
-layout: component
----
+# Progress Ring
 
-```html:preview
+[component-header:sl-progress-ring]
+
+```html preview
 <sl-progress-ring value="25"></sl-progress-ring>
 ```
 
-```jsx:react
-import SlProgressRing from '@shoelace-style/shoelace/dist/react/progress-ring';
+```jsx react
+import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlProgressRing value="25" />;
 ```
@@ -21,56 +18,46 @@ const App = () => <SlProgressRing value="25" />;
 
 Use the `--size` custom property to set the diameter of the progress ring.
 
-```html:preview
+```html preview
 <sl-progress-ring value="50" style="--size: 200px;"></sl-progress-ring>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlProgressRing from '@shoelace-style/shoelace/dist/react/progress-ring';
+```jsx react
+import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlProgressRing value="50" style={{ '--size': '200px' }} />;
 ```
 
-{% endraw %}
-
 ### Track and Indicator Width
 
 Use the `--track-width` and `--indicator-width` custom properties to set the width of the progress ring's track and indicator.
 
-```html:preview
+```html preview
 <sl-progress-ring value="50" style="--track-width: 6px; --indicator-width: 12px;"></sl-progress-ring>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlProgressRing from '@shoelace-style/shoelace/dist/react/progress-ring';
+```jsx react
+import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlProgressRing value="50" style={{ '--track-width': '6px', '--indicator-width': '12px' }} />;
 ```
 
-{% endraw %}
-
 ### Colors
 
 To change the color, use the `--track-color` and `--indicator-color` custom properties.
 
-```html:preview
+```html preview
 <sl-progress-ring
   value="50"
   style="
-    --track-color: pink;
+    --track-color: pink; 
     --indicator-color: deeppink;
   "
 ></sl-progress-ring>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlProgressRing from '@shoelace-style/shoelace/dist/react/progress-ring';
+```jsx react
+import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlProgressRing
@@ -83,18 +70,16 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Labels
 
 Use the `label` attribute to label the progress ring and tell assistive devices how to announce it.
 
-```html:preview
+```html preview
 <sl-progress-ring value="50" label="Upload progress"></sl-progress-ring>
 ```
 
-```jsx:react
-import SlProgressRing from '@shoelace-style/shoelace/dist/react/progress-ring';
+```jsx react
+import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlProgressRing value="50" label="Upload progress" />;
 ```
@@ -103,7 +88,7 @@ const App = () => <SlProgressRing value="50" label="Upload progress" />;
 
 Use the default slot to show a label inside the progress ring.
 
-```html:preview
+```html preview
 <sl-progress-ring value="50" class="progress-ring-values" style="margin-bottom: .5rem;">50%</sl-progress-ring>
 
 <br />
@@ -130,13 +115,9 @@ Use the default slot to show a label inside the progress ring.
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlProgressRing from '@shoelace-style/shoelace/dist/react/progress-ring';
+import { SlButton, SlIcon, SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [value, setValue] = useState(50);
@@ -168,4 +149,4 @@ const App = () => {
 };
 ```
 
-{% endraw %}
+[component-metadata:sl-progress-ring]

docs/components/qr-code.md

@@ -1,13 +1,10 @@
----
-meta:
-  title: QR Code
-  description: Generates a QR code and renders it using the Canvas API.
-layout: component
----
+# QR Code
+
+[component-header:sl-qr-code]
 
 QR codes are useful for providing small pieces of information to users who can quickly scan them with a smartphone. Most smartphones have built-in QR code scanners, so simply pointing the camera at a QR code will decode it and allow the user to visit a website, dial a phone number, read a message, etc.
 
-```html:preview
+```html preview
 <div class="qr-overview">
   <sl-qr-code value="https://shoelace.style/" label="Scan this code to visit Shoelace on the web!"></sl-qr-code>
   <br />
@@ -37,10 +34,9 @@ QR codes are useful for providing small pieces of information to users who can q
 </style>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlQrCode from '@shoelace-style/shoelace/dist/react/qr-code';
-import SlInput from '@shoelace-style/shoelace/dist/react/input';
+import { SlQrCode, SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .qr-overview {
@@ -76,12 +72,12 @@ const App = () => {
 
 Use the `fill` and `background` attributes to modify the QR code's colors. You should always ensure good contrast for optimal compatibility with QR code scanners.
 
-```html:preview
+```html preview
 <sl-qr-code value="https://shoelace.style/" fill="deeppink" background="white"></sl-qr-code>
 ```
 
-```jsx:react
-import SlQrCode from '@shoelace-style/shoelace/dist/react/qr-code';
+```jsx react
+import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlQrCode value="https://shoelace.style/" fill="deeppink" background="white" />;
 ```
@@ -90,12 +86,12 @@ const App = () => <SlQrCode value="https://shoelace.style/" fill="deeppink" back
 
 Use the `size` attribute to change the size of the QR code.
 
-```html:preview
+```html preview
 <sl-qr-code value="https://shoelace.style/" size="64"></sl-qr-code>
 ```
 
-```jsx:react
-import SlQrCode from '@shoelace-style/shoelace/dist/react/qr-code';
+```jsx react
+import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlQrCode value="https://shoelace.style/" size="64" />;
 ```
@@ -104,12 +100,12 @@ const App = () => <SlQrCode value="https://shoelace.style/" size="64" />;
 
 Create a rounded effect with the `radius` attribute.
 
-```html:preview
+```html preview
 <sl-qr-code value="https://shoelace.style/" radius="0.5"></sl-qr-code>
 ```
 
-```jsx:react
-import SlQrCode from '@shoelace-style/shoelace/dist/react/qr-code';
+```jsx react
+import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlQrCode value="https://shoelace.style/" radius="0.5" />;
 ```
@@ -118,7 +114,7 @@ const App = () => <SlQrCode value="https://shoelace.style/" radius="0.5" />;
 
 QR codes can be rendered with various levels of [error correction](https://www.qrcode.com/en/about/error_correction.html) that can be set using the `error-correction` attribute. This example generates four codes with the same value using different error correction levels.
 
-```html:preview
+```html preview
 <div class="qr-error-correction">
   <sl-qr-code value="https://shoelace.style/" error-correction="L"></sl-qr-code>
   <sl-qr-code value="https://shoelace.style/" error-correction="M"></sl-qr-code>
@@ -135,8 +131,8 @@ QR codes can be rendered with various levels of [error correction](https://www.q
 </style>
 ```
 
-```jsx:react
-import SlQrCode from '@shoelace-style/shoelace/dist/react/qr-code';
+```jsx react
+import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .qr-error-correction {
@@ -161,3 +157,5 @@ const App = () => {
   );
 };
 ```
+
+[component-metadata:sl-qr-code]

docs/components/radio-button.md

@@ -1,13 +1,10 @@
----
-meta:
-  title: Radio Button
-  description: Radios buttons allow the user to select a single option from a group using a button-like control.
-layout: component
----
+# Radio Button
+
+[component-header:sl-radio-button]
 
 Radio buttons are designed to be used with [radio groups](/components/radio-group). When a radio button has focus, the arrow keys can be used to change the selected option just like standard radio controls.
 
-```html:preview
+```html preview
 <sl-radio-group label="Select an option" name="a" value="1">
   <sl-radio-button value="1">Option 1</sl-radio-button>
   <sl-radio-button value="2">Option 2</sl-radio-button>
@@ -15,9 +12,8 @@ Radio buttons are designed to be used with [radio groups](/components/radio-grou
 </sl-radio-group>
 ```
 
-```jsx:react
-import SlRadioButton from '@shoelace-style/shoelace/dist/react/radio-button';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
+```jsx react
+import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRadioGroup label="Select an option" name="a" value="1">
@@ -34,7 +30,7 @@ const App = () => (
 
 To set the initial value and checked state, use the `value` attribute on the containing radio group.
 
-```html:preview
+```html preview
 <sl-radio-group label="Select an option" name="a" value="1">
   <sl-radio-button value="1">Option 1</sl-radio-button>
   <sl-radio-button value="2">Option 2</sl-radio-button>
@@ -42,9 +38,8 @@ To set the initial value and checked state, use the `value` attribute on the con
 </sl-radio-group>
 ```
 
-```jsx:react
-import SlRadioButton from '@shoelace-style/shoelace/dist/react/radio-button';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
+```jsx react
+import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRadioGroup label="Select an option" name="a" value="1">
@@ -59,7 +54,7 @@ const App = () => (
 
 Use the `disabled` attribute to disable a radio button.
 
-```html:preview
+```html preview
 <sl-radio-group label="Select an option" name="a" value="1">
   <sl-radio-button value="1">Option 1</sl-radio-button>
   <sl-radio-button value="2" disabled>Option 2</sl-radio-button>
@@ -67,9 +62,8 @@ Use the `disabled` attribute to disable a radio button.
 </sl-radio-group>
 ```
 
-```jsx:react
-import SlRadioButton from '@shoelace-style/shoelace/dist/react/radio-button';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
+```jsx react
+import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRadioGroup label="Select an option" name="a" value="1">
@@ -86,7 +80,7 @@ const App = () => (
 
 Use the `size` attribute to change a radio button's size.
 
-```html:preview
+```html preview
 <sl-radio-group label="Select an option" name="a" value="1">
   <sl-radio-button size="small" value="1">Option 1</sl-radio-button>
   <sl-radio-button size="small" value="2">Option 2</sl-radio-button>
@@ -110,9 +104,8 @@ Use the `size` attribute to change a radio button's size.
 </sl-radio-group>
 ```
 
-```jsx:react
-import SlRadioButton from '@shoelace-style/shoelace/dist/react/radio-button';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
+```jsx react
+import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRadioGroup label="Select an option" name="a" value="1">
@@ -143,7 +136,7 @@ const App = () => (
 
 Use the `pill` attribute to give radio buttons rounded edges.
 
-```html:preview
+```html preview
 <sl-radio-group label="Select an option" name="a" value="1">
   <sl-radio-button pill size="small" value="1">Option 1</sl-radio-button>
   <sl-radio-button pill size="small" value="2">Option 2</sl-radio-button>
@@ -167,9 +160,8 @@ Use the `pill` attribute to give radio buttons rounded edges.
 </sl-radio-group>
 ```
 
-```jsx:react
-import SlRadioButton from '@shoelace-style/shoelace/dist/react/radio-button';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
+```jsx react
+import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRadioGroup label="Select an option" name="a" value="1">
@@ -200,7 +192,7 @@ const App = () => (
 
 Use the `prefix` and `suffix` slots to add icons.
 
-```html:preview
+```html preview
 <sl-radio-group label="Select an option" name="a" value="1">
   <sl-radio-button value="1">
     <sl-icon slot="prefix" name="archive"></sl-icon>
@@ -220,10 +212,8 @@ Use the `prefix` and `suffix` slots to add icons.
 </sl-radio-group>
 ```
 
-```jsx:react
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlRadioButton from '@shoelace-style/shoelace/dist/react/radio-button';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
+```jsx react
+import { SlIcon, SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRadioGroup label="Select an option" name="a" value="1">
@@ -250,7 +240,7 @@ const App = () => (
 
 You can omit button labels and use icons instead. Make sure to set a `label` attribute on each icon so screen readers will announce each option correctly.
 
-```html:preview
+```html preview
 <sl-radio-group label="Select an option" name="a" value="neutral">
   <sl-radio-button value="angry">
     <sl-icon name="emoji-angry" label="Angry"></sl-icon>
@@ -274,10 +264,8 @@ You can omit button labels and use icons instead. Make sure to set a `label` att
 </sl-radio-group>
 ```
 
-```jsx:react
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlRadioButton from '@shoelace-style/shoelace/dist/react/radio-button';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
+```jsx react
+import { SlIcon, SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRadioGroup label="Select an option" name="a" value="neutral">
@@ -303,3 +291,5 @@ const App = () => (
   </SlRadioGroup>
 );
 ```
+
+[component-metadata:sl-radio-button]

docs/components/radio-group.md

@@ -1,11 +1,8 @@
----
-meta:
-  title: Radio Group
-  description: Radio groups are used to group multiple radios or radio buttons so they function as a single form control.
-layout: component
----
+# Radio Group
 
-```html:preview
+[component-header:sl-radio-group]
+
+```html preview
 <sl-radio-group label="Select an option" name="a" value="1">
   <sl-radio value="1">Option 1</sl-radio>
   <sl-radio value="2">Option 2</sl-radio>
@@ -13,9 +10,8 @@ layout: component
 </sl-radio-group>
 ```
 
-```jsx:react
-import SlRadio from '@shoelace-style/shoelace/dist/react/radio';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
+```jsx react
+import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRadioGroup label="Select an option" name="a" value="1">
@@ -32,7 +28,7 @@ const App = () => (
 
 Add descriptive help text to a radio group with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
 
-```html:preview
+```html preview
 <sl-radio-group label="Select an option" help-text="Choose the most appropriate option." name="a" value="1">
   <sl-radio value="1">Option 1</sl-radio>
   <sl-radio value="2">Option 2</sl-radio>
@@ -40,9 +36,8 @@ Add descriptive help text to a radio group with the `help-text` attribute. For h
 </sl-radio-group>
 ```
 
-```jsx:react
-import SlRadio from '@shoelace-style/shoelace/dist/react/radio';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
+```jsx react
+import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRadioGroup label="Select an option" help-text="Choose the most appropriate option." name="a" value="1">
@@ -57,7 +52,7 @@ const App = () => (
 
 [Radio buttons](/components/radio-button) offer an alternate way to display radio controls. In this case, an internal [button group](/components/button-group) is used to group the buttons into a single, cohesive control.
 
-```html:preview
+```html preview
 <sl-radio-group label="Select an option" help-text="Select an option that makes you proud." name="a" value="1">
   <sl-radio-button value="1">Option 1</sl-radio-button>
   <sl-radio-button value="2">Option 2</sl-radio-button>
@@ -65,9 +60,8 @@ const App = () => (
 </sl-radio-group>
 ```
 
-```jsx:react
-import SlRadioButton from '@shoelace-style/shoelace/dist/react/radio-button';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
+```jsx react
+import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRadioGroup label="Select an option" name="a" value="1">
@@ -82,7 +76,7 @@ const App = () => (
 
 Radios and radio buttons can be disabled by adding the `disabled` attribute to the respective options inside the radio group.
 
-```html:preview
+```html preview
 <sl-radio-group label="Select an option" name="a" value="1">
   <sl-radio value="1">Option 1</sl-radio>
   <sl-radio value="2" disabled>Option 2</sl-radio>
@@ -90,9 +84,8 @@ Radios and radio buttons can be disabled by adding the `disabled` attribute to t
 </sl-radio-group>
 ```
 
-```jsx:react
-import SlRadio from '@shoelace-style/shoelace/dist/react/radio';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
+```jsx react
+import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRadioGroup label="Select an option" name="a" value="1">
@@ -105,61 +98,11 @@ const App = () => (
 );
 ```
 
-### Sizing Options
-
-The size of [Radios](/components/radio) and [Radio Buttons](/components/radio-buttons) will be determined by the Radio Group's `size` attribute.
-
-```html preview
-<sl-radio-group label="Select an option" size="medium" value="medium" class="radio-group-size">
-  <sl-radio value="small">Small</sl-radio>
-  <sl-radio value="medium">Medium</sl-radio>
-  <sl-radio value="large">Large</sl-radio>
-</sl-radio-group>
-
-<script>
-  const radioGroup = document.querySelector('.radio-group-size');
-
-  radioGroup.addEventListener('sl-change', () => {
-    radioGroup.size = radioGroup.value;
-  });
-</script>
-```
-
-```jsx react
-import { useState } from 'react';
-import SlRadio from '@shoelace-style/shoelace/dist/react/radio';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
-
-const App = () => {
-  const [size, setSize] = useState('medium');
-
-  return (
-    <>
-      <SlRadioGroup
-        label="Select an option"
-        size={size}
-        value={size}
-        class="radio-group-size"
-        onSlChange={event => setSize(event.target.value)}
-      >
-        <SlRadio value="small">Small</SlRadio>
-        <SlRadio value="medium">Medium</SlRadio>
-        <SlRadio value="large">Large</SlRadio>
-      </SlRadioGroup>
-    </>
-  );
-};
-```
-
-:::tip
-[Radios](/components/radio) and [Radio Buttons](/components/radio-button) also have a `size` attribute. This can be useful in certain compositions, but it will be ignored when used inside of a Radio Group.
-:::
-
 ### Validation
 
 Setting the `required` attribute to make selecting an option mandatory. If a value has not been selected, it will prevent the form from submitting and display an error message.
 
-```html:preview
+```html preview
 <form class="validation">
   <sl-radio-group label="Select an option" name="a" required>
     <sl-radio value="1">Option 1</sl-radio>
@@ -181,11 +124,8 @@ Setting the `required` attribute to make selecting an option mandatory. If a val
 </script>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlRadio from '@shoelace-style/shoelace/dist/react/radio';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
+```jsx react
+import { SlButton, SlIcon, SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 const App = () => {
   function handleSubmit(event) {
     event.preventDefault();
@@ -218,7 +158,7 @@ const App = () => {
 
 Use the `setCustomValidity()` method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.
 
-```html:preview
+```html preview
 <form class="custom-validity">
   <sl-radio-group label="Select an option" name="a" value="1">
     <sl-radio value="1">Not me</sl-radio>
@@ -253,12 +193,9 @@ Use the `setCustomValidity()` method to set a custom validation message. This wi
 </script>
 ```
 
-```jsx:react
+```jsx react
 import { useEffect, useRef } from 'react';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlRadio from '@shoelace-style/shoelace/dist/react/radio';
-import SlRadioGroup from '@shoelace-style/shoelace/dist/react/radio-group';
+import { SlButton, SlIcon, SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 const App = () => {
   const radioGroup = useRef(null);
   const errorMessage = 'You must choose this option';
@@ -291,3 +228,5 @@ const App = () => {
   );
 };
 ```
+
+[component-metadata:sl-radio-group]

docs/components/radio.md

@@ -0,0 +1,105 @@
+# Radio
+
+[component-header:sl-radio]
+
+Radios are designed to be used with [radio groups](/components/radio-group).
+
+```html preview
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio value="1">Option 1</sl-radio>
+  <sl-radio value="2">Option 2</sl-radio>
+  <sl-radio value="3">Option 3</sl-radio>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadio value="1">Option 1</SlRadio>
+    <SlRadio value="2">Option 2</SlRadio>
+    <SlRadio value="3">Option 3</SlRadio>
+  </SlRadioGroup>
+);
+```
+
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
+
+## Examples
+
+### Initial Value
+
+To set the initial value and checked state, use the `value` attribute on the containing radio group.
+
+```html preview
+<sl-radio-group label="Select an option" name="a" value="3">
+  <sl-radio value="1">Option 1</sl-radio>
+  <sl-radio value="2">Option 2</sl-radio>
+  <sl-radio value="3">Option 3</sl-radio>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="3">
+    <SlRadio value="1">Option 1</SlRadio>
+    <SlRadio value="2">Option 2</SlRadio>
+    <SlRadio value="3">Option 3</SlRadio>
+  </SlRadioGroup>
+);
+```
+
+### Disabled
+
+Use the `disabled` attribute to disable a radio.
+
+```html preview
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio value="1">Option 1</sl-radio>
+  <sl-radio value="2" disabled>Option 2</sl-radio>
+  <sl-radio value="3">Option 3</sl-radio>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadio value="1">Option 1</SlRadio>
+    <SlRadio value="2" disabled>
+      Option 2
+    </SlRadio>
+    <SlRadio value="3">Option 3</SlRadio>
+  </SlRadioGroup>
+);
+```
+
+## Sizes
+
+Use the `size` attribute to change a radio's size.
+
+```html preview
+<sl-radio size="small">Small</sl-radio>
+<sl-radio size="medium">Medium</sl-radio>
+<sl-radio size="large">Large</sl-radio>
+```
+
+```jsx react
+import { SlRadio } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlRadio size="small">Small</SlRadio>
+    <br />
+    <SlRadio size="medium">Medium</SlRadio>
+    <br />
+    <SlRadio size="large">Large</SlRadio>
+  </>
+);
+```
+
+[component-metadata:sl-radio]

docs/components/range.md

@@ -1,23 +1,18 @@
----
-meta:
-  title: Range
-  description: Ranges allow the user to select a single value within a given range using a slider.
-layout: component
----
+# Range
 
-```html:preview
+[component-header:sl-range]
+
+```html preview
 <sl-range></sl-range>
 ```
 
-```jsx:react
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRange />;
 ```
 
-:::tip
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
-:::
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
@@ -25,12 +20,12 @@ This component works with standard `<form>` elements. Please refer to the sectio
 
 Use the `label` attribute to give the range an accessible label. For labels that contain HTML, use the `label` slot instead.
 
-```html:preview
+```html preview
 <sl-range label="Volume" min="0" max="100"></sl-range>
 ```
 
-```jsx:react
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRange label="Volume" min={0} max={100} />;
 ```
@@ -39,12 +34,12 @@ const App = () => <SlRange label="Volume" min={0} max={100} />;
 
 Add descriptive help text to a range with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
 
-```html:preview
+```html preview
 <sl-range label="Volume" help-text="Controls the volume of the current song." min="0" max="100"></sl-range>
 ```
 
-```jsx:react
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRange label="Volume" help-text="Controls the volume of the current song." min={0} max={100} />;
 ```
@@ -53,12 +48,12 @@ const App = () => <SlRange label="Volume" help-text="Controls the volume of the
 
 Use the `min` and `max` attributes to set the range's minimum and maximum values, respectively. The `step` attribute determines the value's interval when increasing and decreasing.
 
-```html:preview
+```html preview
 <sl-range min="0" max="10" step="1"></sl-range>
 ```
 
-```jsx:react
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRange min={0} max={10} step={1} />;
 ```
@@ -67,12 +62,12 @@ const App = () => <SlRange min={0} max={10} step={1} />;
 
 Use the `disabled` attribute to disable a slider.
 
-```html:preview
+```html preview
 <sl-range disabled></sl-range>
 ```
 
-```jsx:react
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRange disabled />;
 ```
@@ -81,12 +76,12 @@ const App = () => <SlRange disabled />;
 
 By default, the tooltip is shown on top. Set `tooltip` to `bottom` to show it below the slider.
 
-```html:preview
+```html preview
 <sl-range tooltip="bottom"></sl-range>
 ```
 
-```jsx:react
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRange tooltip="bottom" />;
 ```
@@ -95,12 +90,12 @@ const App = () => <SlRange tooltip="bottom" />;
 
 To disable the tooltip, set `tooltip` to `none`.
 
-```html:preview
+```html preview
 <sl-range tooltip="none"></sl-range>
 ```
 
-```jsx:react
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRange tooltip="none" />;
 ```
@@ -109,7 +104,7 @@ const App = () => <SlRange tooltip="none" />;
 
 You can customize the active and inactive portions of the track using the `--track-color-active` and `--track-color-inactive` custom properties.
 
-```html:preview
+```html preview
 <sl-range
   style="
   --track-color-active: var(--sl-color-primary-600);
@@ -118,10 +113,8 @@ You can customize the active and inactive portions of the track using the `--tra
 ></sl-range>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRange
@@ -133,13 +126,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Custom Track Offset
 
 You can customize the initial offset of the active track using the `--track-active-offset` custom property.
 
-```html:preview
+```html preview
 <sl-range
   min="-100"
   max="100"
@@ -151,10 +142,8 @@ You can customize the initial offset of the active track using the `--track-acti
 ></sl-range>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRange
@@ -169,13 +158,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Custom Tooltip Formatter
 
 You can change the tooltip's content by setting the `tooltipFormatter` property to a function that accepts the range's value as an argument.
 
-```html:preview
+```html preview
 <sl-range min="0" max="100" step="1" class="range-with-custom-formatter"></sl-range>
 
 <script>
@@ -184,8 +171,10 @@ You can change the tooltip's content by setting the `tooltipFormatter` property
 </script>
 ```
 
-```jsx:react
-import SlRange from '@shoelace-style/shoelace/dist/react/range';
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRange min={0} max={100} step={1} tooltipFormatter={value => `Total - ${value}%`} />;
 ```
+
+[component-metadata:sl-range]

docs/components/rating.md

@@ -1,16 +1,13 @@
----
-meta:
-  title: Rating
-  description: Ratings give users a way to quickly view and provide feedback.
-layout: component
----
+# Rating
 
-```html:preview
+[component-header:sl-rating]
+
+```html preview
 <sl-rating label="Rating"></sl-rating>
 ```
 
-```jsx:react
-import SlRating from '@shoelace-style/shoelace/dist/react/rating';
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRating label="Rating" />;
 ```
@@ -21,12 +18,12 @@ const App = () => <SlRating label="Rating" />;
 
 Ratings are commonly identified contextually, so labels aren't displayed. However, you should always provide one for assistive devices using the `label` attribute.
 
-```html:preview
+```html preview
 <sl-rating label="Rate this component"></sl-rating>
 ```
 
-```jsx:react
-import SlRating from '@shoelace-style/shoelace/dist/react/rating';
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRating label="Rate this component" />;
 ```
@@ -35,12 +32,12 @@ const App = () => <SlRating label="Rate this component" />;
 
 Ratings are 0-5 by default. To change the maximum possible value, use the `max` attribute.
 
-```html:preview
+```html preview
 <sl-rating label="Rating" max="3"></sl-rating>
 ```
 
-```jsx:react
-import SlRating from '@shoelace-style/shoelace/dist/react/rating';
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRating label="Rating" max={3} />;
 ```
@@ -49,12 +46,12 @@ const App = () => <SlRating label="Rating" max={3} />;
 
 Use the `precision` attribute to let users select fractional ratings.
 
-```html:preview
+```html preview
 <sl-rating label="Rating" precision="0.5" value="2.5"></sl-rating>
 ```
 
-```jsx:react
-import SlRating from '@shoelace-style/shoelace/dist/react/rating';
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRating label="Rating" precision={0.5} value={2.5} />;
 ```
@@ -63,30 +60,26 @@ const App = () => <SlRating label="Rating" precision={0.5} value={2.5} />;
 
 Set the `--symbol-size` custom property to adjust the size.
 
-```html:preview
+```html preview
 <sl-rating label="Rating" style="--symbol-size: 2rem;"></sl-rating>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlRating from '@shoelace-style/shoelace/dist/react/rating';
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRating label="Rating" style={{ '--symbol-size': '2rem' }} />;
 ```
 
-{% endraw %}
-
 ### Readonly
 
 Use the `readonly` attribute to display a rating that users can't change.
 
-```html:preview
+```html preview
 <sl-rating label="Rating" readonly value="3"></sl-rating>
 ```
 
-```jsx:react
-import SlRating from '@shoelace-style/shoelace/dist/react/rating';
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRating label="Rating" readonly value={3} />;
 ```
@@ -95,12 +88,12 @@ const App = () => <SlRating label="Rating" readonly value={3} />;
 
 Use the `disable` attribute to disable the rating.
 
-```html:preview
+```html preview
 <sl-rating label="Rating" disabled value="3"></sl-rating>
 ```
 
-```jsx:react
-import SlRating from '@shoelace-style/shoelace/dist/react/rating';
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRating label="Rating" disabled value={3} />;
 ```
@@ -111,7 +104,7 @@ Use the `sl-hover` event to detect when the user hovers over (or touch and drag)
 
 The event has a payload with `phase` and `value` properties. The `phase` property tells when hovering starts, moves to a new value, and ends. The `value` property tells what the rating's value would be if the user were to commit to the hovered value.
 
-```html:preview
+```html preview
 <div class="detect-hover">
   <sl-rating label="Rating"></sl-rating>
   <span></span>
@@ -150,9 +143,9 @@ The event has a payload with `phase` and `value` properties. The `phase` propert
 </style>
 ```
 
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlRating from '@shoelace-style/shoelace/dist/react/rating';
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const terms = ['No rating', 'Terrible', 'Bad', 'OK', 'Good', 'Excellent'];
 const css = `
@@ -202,7 +195,7 @@ const App = () => {
 
 You can provide custom icons by passing a function to the `getSymbol` property.
 
-```html:preview
+```html preview
 <sl-rating label="Rating" class="rating-hearts" style="--symbol-color-active: #ff4136;"></sl-rating>
 
 <script>
@@ -211,10 +204,8 @@ You can provide custom icons by passing a function to the `getSymbol` property.
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlRating from '@shoelace-style/shoelace/dist/react/rating';
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlRating
@@ -225,13 +216,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Value-based Icons
 
 You can also use the `getSymbol` property to render different icons based on value.
 
-```html:preview
+```html preview
 <sl-rating label="Rating" class="rating-emojis"></sl-rating>
 
 <script>
@@ -244,8 +233,8 @@ You can also use the `getSymbol` property to render different icons based on val
 </script>
 ```
 
-```jsx:react
-import SlRating from '@shoelace-style/shoelace/dist/react/rating';
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 function getSymbol(value) {
   const icons = ['emoji-angry', 'emoji-frown', 'emoji-expressionless', 'emoji-smile', 'emoji-laughing'];
@@ -254,3 +243,5 @@ function getSymbol(value) {
 
 const App = () => <SlRating label="Rating" getSymbol={getSymbol} />;
 ```
+
+[component-metadata:sl-rating]

docs/components/relative-time.md

@@ -1,28 +1,23 @@
----
-meta:
-  title: Relative Time
-  description: Outputs a localized time phrase relative to the current date and time.
-layout: component
----
+# Relative Time
+
+[component-header:sl-relative-time]
 
 Localization is handled by the browser's [`Intl.RelativeTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat). No language packs are required.
 
-```html:preview
+```html preview
 <!-- Shoelace 2 release date 🎉 -->
 <sl-relative-time date="2020-07-15T09:17:00-04:00"></sl-relative-time>
 ```
 
-```jsx:react
-import SlRelativeTime from '@shoelace-style/shoelace/dist/react/relative-time';
+```jsx react
+import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlRelativeTime date="2020-07-15T09:17:00-04:00" />;
 ```
 
 The `date` attribute determines when the date/time is calculated from. It must be a string that [`Date.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse) can interpret or a [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object set via JavaScript.
 
-:::tip
-When using strings, avoid ambiguous dates such as `03/04/2020` which can be interpreted as March 4 or April 3 depending on the user's browser and locale. Instead, always use a valid [ISO 8601 date time string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse#Date_Time_String_Format) to ensure the date will be parsed properly by all clients.
-:::
+?> When using strings, avoid ambiguous dates such as `03/04/2020` which can be interpreted as March 4 or April 3 depending on the user's browser and locale. Instead, always use a valid [ISO 8601 date time string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse#Date_Time_String_Format) to ensure the date will be parsed properly by all clients.
 
 ## Examples
 
@@ -30,7 +25,7 @@ When using strings, avoid ambiguous dates such as `03/04/2020` which can be inte
 
 Use the `sync` attribute to update the displayed value automatically as time passes.
 
-```html:preview
+```html preview
 <div class="relative-time-sync">
   <sl-relative-time sync></sl-relative-time>
 </div>
@@ -43,8 +38,8 @@ Use the `sync` attribute to update the displayed value automatically as time pas
 </script>
 ```
 
-```jsx:react
-import SlRelativeTime from '@shoelace-style/shoelace/dist/react/relative-time';
+```jsx react
+import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
 
 const date = new Date(new Date().getTime() - 60000);
 
@@ -55,14 +50,14 @@ const App = () => <SlRelativeTime date={date} sync />;
 
 You can change how the time is displayed using the `format` attribute. Note that some locales may display the same values for `narrow` and `short` formats.
 
-```html:preview
+```html preview
 <sl-relative-time date="2020-07-15T09:17:00-04:00" format="narrow"></sl-relative-time><br />
 <sl-relative-time date="2020-07-15T09:17:00-04:00" format="short"></sl-relative-time><br />
 <sl-relative-time date="2020-07-15T09:17:00-04:00" format="long"></sl-relative-time>
 ```
 
-```jsx:react
-import SlRelativeTime from '@shoelace-style/shoelace/dist/react/relative-time';
+```jsx react
+import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -79,7 +74,7 @@ const App = () => (
 
 Use the `lang` attribute to set the desired locale.
 
-```html:preview
+```html preview
 English: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="en-US"></sl-relative-time><br />
 Chinese: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="zh-CN"></sl-relative-time><br />
 German: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="de"></sl-relative-time><br />
@@ -87,8 +82,8 @@ Greek: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="el"></sl-relativ
 Russian: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="ru"></sl-relative-time>
 ```
 
-```jsx:react
-import SlRelativeTime from '@shoelace-style/shoelace/dist/react/relative-time';
+```jsx react
+import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -104,3 +99,5 @@ const App = () => (
   </>
 );
 ```
+
+[component-metadata:sl-relative-time]

docs/components/resize-observer.md

@@ -1,13 +1,10 @@
----
-meta:
-  title: Resize Observer
-  description: The Resize Observer component offers a thin, declarative interface to the ResizeObserver API.
-layout: component
----
+# Resize Observer
+
+[component-header:sl-resize-observer]
 
 The resize observer will report changes to the dimensions of the elements it wraps through the `sl-resize` event. When emitted, a collection of [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects will be attached to `event.detail` that contains the target element and information about its dimensions.
 
-```html:preview
+```html preview
 <div class="resize-observer-overview">
   <sl-resize-observer>
     <div>Resize this box and watch the console 👉</div>
@@ -35,14 +32,14 @@ The resize observer will report changes to the dimensions of the elements it wra
 </style>
 ```
 
-```jsx:react
-import SlResizeObserver from '@shoelace-style/shoelace/dist/react/resize-observer';
+```jsx react
+import { SlResizeObserver } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .resize-observer-overview div {
-    display: flex;
-    border: solid 2px var(--sl-input-border-color);
-    align-items: center;
+    display: flex; 
+    border: solid 2px var(--sl-input-border-color); 
+    align-items: center; 
     justify-content: center;
     text-align: center;
     padding: 4rem 2rem;
@@ -61,3 +58,5 @@ const App = () => (
   </>
 );
 ```
+
+[component-metadata:sl-resize-observer]

docs/components/select.md

@@ -1,11 +1,8 @@
----
-meta:
-  title: Select
-  description: Selects allow you to choose items from a menu of predefined options.
-layout: component
----
+# Select
 
-```html:preview
+[component-header:sl-select]
+
+```html preview
 <sl-select>
   <sl-option value="option-1">Option 1</sl-option>
   <sl-option value="option-2">Option 2</sl-option>
@@ -16,9 +13,8 @@ layout: component
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect>
@@ -32,9 +28,7 @@ const App = () => (
 );
 ```
 
-:::tip
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
-:::
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
@@ -42,7 +36,7 @@ This component works with standard `<form>` elements. Please refer to the sectio
 
 Use the `label` attribute to give the select an accessible label. For labels that contain HTML, use the `label` slot instead.
 
-```html:preview
+```html preview
 <sl-select label="Select one">
   <sl-option value="option-1">Option 1</sl-option>
   <sl-option value="option-2">Option 2</sl-option>
@@ -50,9 +44,8 @@ Use the `label` attribute to give the select an accessible label. For labels tha
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect label="Select one">
@@ -67,7 +60,7 @@ const App = () => (
 
 Add descriptive help text to a select with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
 
-```html:preview
+```html preview
 <sl-select label="Experience" help-text="Please tell us your skill level.">
   <sl-option value="1">Novice</sl-option>
   <sl-option value="2">Intermediate</sl-option>
@@ -75,9 +68,8 @@ Add descriptive help text to a select with the `help-text` attribute. For help t
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect label="Experience" help-text="Please tell us your skill level.">
@@ -92,7 +84,7 @@ const App = () => (
 
 Use the `placeholder` attribute to add a placeholder.
 
-```html:preview
+```html preview
 <sl-select placeholder="Select one">
   <sl-option value="option-1">Option 1</sl-option>
   <sl-option value="option-2">Option 2</sl-option>
@@ -100,9 +92,8 @@ Use the `placeholder` attribute to add a placeholder.
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect placeholder="Select one">
@@ -117,7 +108,7 @@ const App = () => (
 
 Use the `clearable` attribute to make the control clearable. The clear button only appears when an option is selected.
 
-```html:preview
+```html preview
 <sl-select clearable value="option-1">
   <sl-option value="option-1">Option 1</sl-option>
   <sl-option value="option-2">Option 2</sl-option>
@@ -125,9 +116,8 @@ Use the `clearable` attribute to make the control clearable. The clear button on
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect placeholder="Clearable" clearable>
@@ -142,7 +132,7 @@ const App = () => (
 
 Add the `filled` attribute to draw a filled select.
 
-```html:preview
+```html preview
 <sl-select filled>
   <sl-option value="option-1">Option 1</sl-option>
   <sl-option value="option-2">Option 2</sl-option>
@@ -150,9 +140,8 @@ Add the `filled` attribute to draw a filled select.
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect filled>
@@ -167,7 +156,7 @@ const App = () => (
 
 Use the `pill` attribute to give selects rounded edges.
 
-```html:preview
+```html preview
 <sl-select pill>
   <sl-option value="option-1">Option 1</sl-option>
   <sl-option value="option-2">Option 2</sl-option>
@@ -175,9 +164,8 @@ Use the `pill` attribute to give selects rounded edges.
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect pill>
@@ -192,7 +180,7 @@ const App = () => (
 
 Use the `disabled` attribute to disable a select.
 
-```html:preview
+```html preview
 <sl-select placeholder="Disabled" disabled>
   <sl-option value="option-1">Option 1</sl-option>
   <sl-option value="option-2">Option 2</sl-option>
@@ -200,9 +188,8 @@ Use the `disabled` attribute to disable a select.
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect placeholder="Disabled" disabled>
@@ -217,7 +204,7 @@ const App = () => (
 
 To allow multiple options to be selected, use the `multiple` attribute. It's a good practice to use `clearable` when this option is enabled. To set multiple values at once, set `value` to a space-delimited list of values.
 
-```html:preview
+```html preview
 <sl-select label="Select a Few" value="option-1 option-2 option-3" multiple clearable>
   <sl-option value="option-1">Option 1</sl-option>
   <sl-option value="option-2">Option 2</sl-option>
@@ -228,9 +215,8 @@ To allow multiple options to be selected, use the `multiple` attribute. It's a g
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect label="Select a Few" value="option-1 option-2 option-3" multiple clearable>
@@ -244,17 +230,13 @@ const App = () => (
 );
 ```
 
-:::tip
-Note that multi-select options may wrap, causing the control to expand vertically. You can use the `max-options-visible` attribute to control the maximum number of selected options to show at once.
-:::
+?> Note that multi-select options may wrap, causing the control to expand vertically. You can use the `max-options-visible` attribute to control the maximum number of selected options to show at once.
 
 ### Setting Initial Values
 
-Use the `value` attribute to set the initial selection.
+Use the `value` attribute to set the initial selection. When using `multiple`, use space-delimited values to select more than one option.
 
-When using `multiple`, the `value` _attribute_ uses space-delimited values to select more than one option. Because of this, `<sl-option>` values cannot contain spaces. If you're accessing the `value` _property_ through Javascript, it will be an array.
-
-```html:preview
+```html preview
 <sl-select value="option-1 option-2" multiple clearable>
   <sl-option value="option-1">Option 1</sl-option>
   <sl-option value="option-2">Option 2</sl-option>
@@ -263,10 +245,8 @@ When using `multiple`, the `value` _attribute_ uses space-delimited values to se
 </sl-select>
 ```
 
-```jsx:react
-import SlDivider from '@shoelace-style/shoelace/dist/react/divider';
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlDivider, SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect value="option-1 option-2" multiple clearable>
@@ -281,7 +261,7 @@ const App = () => (
 
 Use `<sl-divider>` to group listbox items visually. You can also use `<small>` to provide labels, but they won't be announced by most assistive devices.
 
-```html:preview
+```html preview
 <sl-select>
   <small>Section 1</small>
   <sl-option value="option-1">Option 1</sl-option>
@@ -295,9 +275,8 @@ Use `<sl-divider>` to group listbox items visually. You can also use `<small>` t
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect>
@@ -315,7 +294,7 @@ const App = () => (
 
 Use the `size` attribute to change a select's size. Note that size does not apply to listbox options.
 
-```html:preview
+```html preview
 <sl-select placeholder="Small" size="small">
   <sl-option value="option-1">Option 1</sl-option>
   <sl-option value="option-2">Option 2</sl-option>
@@ -339,9 +318,8 @@ Use the `size` attribute to change a select's size. Note that size does not appl
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -374,7 +352,7 @@ const App = () => (
 
 The preferred placement of the select's listbox can be set with the `placement` attribute. Note that the actual position may vary to ensure the panel remains in the viewport. Valid placements are `top` and `bottom`.
 
-```html:preview
+```html preview
 <sl-select placement="top">
   <sl-option value="option-1">Option 1</sl-option>
   <sl-option value="option-2">Option 2</sl-option>
@@ -382,9 +360,11 @@ The preferred placement of the select's listbox can be set with the `placement`
 </sl-select>
 ```
 
-```jsx:react
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import {
+  SlOption,
+  SlSelect
+} from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect placement="top">
@@ -399,7 +379,7 @@ const App = () => (
 
 Use the `prefix` slot to prepend an icon to the control.
 
-```html:preview
+```html preview
 <sl-select placeholder="Small" size="small" clearable>
   <sl-icon name="house" slot="prefix"></sl-icon>
   <sl-option value="option-1">Option 1</sl-option>
@@ -422,10 +402,8 @@ Use the `prefix` slot to prepend an icon to the control.
 </sl-select>
 ```
 
-```jsx:react
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
-import SlOption from '@shoelace-style/shoelace/dist/react/option';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
+```jsx react
+import { SlIcon, SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -453,52 +431,4 @@ const App = () => (
 );
 ```
 
-### Custom Tags
-
-When multiple options can be selected, you can provide custom tags by passing a function to the `getTag` property. Your function can return a string of HTML, a <a href="https://lit.dev/docs/templates/overview/">Lit Template</a>, or an [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement). The `getTag()` function will be called for each option. The first argument is an `<sl-option>` element and the second argument is the tag's index (its position in the tag list).
-
-Remember that custom tags are rendered in a shadow root. To style them, you can use the `style` attribute in your template or you can add your own [parts](/getting-started/customizing/#css-parts) and target them with the [`::part()`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) selector.
-
-```html:preview
-<sl-select
-  placeholder="Select one"
-  value="email phone"
-  multiple
-  clearable
-  class="custom-tag"
->
-  <sl-option value="email">
-    <sl-icon slot="prefix" name="envelope"></sl-icon>
-    Email
-  </sl-option>
-  <sl-option value="phone">
-    <sl-icon slot="prefix" name="telephone"></sl-icon>
-    Phone
-  </sl-option>
-  <sl-option value="chat">
-    <sl-icon slot="prefix" name="chat-dots"></sl-icon>
-    Chat
-  </sl-option>
-</sl-select>
-
-<script type="module">
-  const select = document.querySelector('.custom-tag');
-
-  select.getTag = (option, index) => {
-    // Use the same icon used in the <sl-option>
-    const name = option.querySelector('sl-icon[slot="prefix"]').name;
-
-    // You can return a string, a Lit Template, or an HTMLElement here
-    return `
-      <sl-tag removable>
-        <sl-icon name="${name}" style="padding-inline-end: .5rem;"></sl-icon>
-        ${option.getTextLabel()}
-      </sl-tag>
-    `;
-  };
-</script>
-```
-
-:::warning
-Be sure you trust the content you are outputting! Passing unsanitized user input to `getTag()` can result in XSS vulnerabilities.
-:::
+[component-metadata:sl-select]

docs/components/skeleton.md

@@ -1,15 +1,12 @@
----
-meta:
-  title: Skeleton
-  description: Skeletons are used to provide a visual representation of where content will eventually be drawn.
-layout: component
----
+# Skeleton
+
+[component-header:sl-skeleton]
 
 These are simple containers for scaffolding layouts that mimic what users will see when content has finished loading. This prevents large areas of empty space during asynchronous operations.
 
 Skeletons try not to be opinionated, as there are endless possibilities for designing layouts. Therefore, you'll likely use more than one skeleton to create the effect you want. If you find yourself using them frequently, consider creating a template that renders them with the desired arrangement and styles.
 
-```html:preview
+```html preview
 <div class="skeleton-overview">
   <header>
     <sl-skeleton></sl-skeleton>
@@ -55,8 +52,8 @@ Skeletons try not to be opinionated, as there are endless possibilities for desi
 </style>
 ```
 
-```jsx:react
-import SlSkeleton from '@shoelace-style/shoelace/dist/react/skeleton';
+```jsx react
+import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .skeleton-overview header {
@@ -115,7 +112,7 @@ const App = () => (
 
 There are two built-in effects, `sheen` and `pulse`. Effects are intentionally subtle, as they can be distracting when used extensively. The default is `none`, which displays a static, non-animated skeleton.
 
-```html:preview
+```html preview
 <div class="skeleton-effects">
   <sl-skeleton effect="none"></sl-skeleton>
   None
@@ -138,8 +135,8 @@ There are two built-in effects, `sheen` and `pulse`. Effects are intentionally s
 </style>
 ```
 
-```jsx:react
-import SlSkeleton from '@shoelace-style/shoelace/dist/react/skeleton';
+```jsx react
+import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .skeleton-effects {
@@ -171,7 +168,7 @@ const App = () => (
 
 Use multiple skeletons and some clever styles to simulate paragraphs.
 
-```html:preview
+```html preview
 <div class="skeleton-paragraphs">
   <sl-skeleton></sl-skeleton>
   <sl-skeleton></sl-skeleton>
@@ -199,8 +196,8 @@ Use multiple skeletons and some clever styles to simulate paragraphs.
 </style>
 ```
 
-```jsx:react
-import SlSkeleton from '@shoelace-style/shoelace/dist/react/skeleton';
+```jsx react
+import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .skeleton-paragraphs sl-skeleton {
@@ -239,7 +236,7 @@ const App = () => (
 
 Set a matching width and height to make a circle, square, or rounded avatar skeleton.
 
-```html:preview
+```html preview
 <div class="skeleton-avatars">
   <sl-skeleton></sl-skeleton>
   <sl-skeleton></sl-skeleton>
@@ -264,8 +261,8 @@ Set a matching width and height to make a circle, square, or rounded avatar skel
 </style>
 ```
 
-```jsx:react
-import SlSkeleton from '@shoelace-style/shoelace/dist/react/skeleton';
+```jsx react
+import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .skeleton-avatars sl-skeleton {
@@ -278,7 +275,7 @@ const css = `
   .skeleton-avatars sl-skeleton:nth-child(1) {
     --border-radius: 0;
   }
-
+  
   .skeleton-avatars sl-skeleton:nth-child(2) {
     --border-radius: var(--sl-border-radius-medium);
   }
@@ -301,7 +298,7 @@ const App = () => (
 
 Use the `--border-radius` custom property to make circles, squares, and rectangles. For more complex shapes, you can apply `clip-path` to the `indicator` part. [Try Clippy](https://bennettfeely.com/clippy/) if you need help generating custom shapes.
 
-```html:preview
+```html preview
 <div class="skeleton-shapes">
   <sl-skeleton class="square"></sl-skeleton>
   <sl-skeleton class="circle"></sl-skeleton>
@@ -359,8 +356,8 @@ Use the `--border-radius` custom property to make circles, squares, and rectangl
 </style>
 ```
 
-```jsx:react
-import SlSkeleton from '@shoelace-style/shoelace/dist/react/skeleton';
+```jsx react
+import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .skeleton-shapes sl-skeleton {
@@ -416,14 +413,12 @@ const App = () => (
 
 Set the `--color` and `--sheen-color` custom properties to adjust the skeleton's color.
 
-```html:preview
+```html preview
 <sl-skeleton effect="sheen" style="--color: tomato; --sheen-color: #ffb094;"></sl-skeleton>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSkeleton from '@shoelace-style/shoelace/dist/react/skeleton';
+```jsx react
+import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .skeleton-avatars sl-skeleton {
@@ -436,7 +431,7 @@ const css = `
   .skeleton-avatars sl-skeleton:nth-child(1) {
     --border-radius: 0;
   }
-
+  
   .skeleton-avatars sl-skeleton:nth-child(2) {
     --border-radius: var(--sl-border-radius-medium);
   }
@@ -445,4 +440,4 @@ const css = `
 const App = () => <SlSkeleton effect="sheen" style={{ '--color': 'tomato', '--sheen-color': '#ffb094' }} />;
 ```
 
-{% endraw %}
+[component-metadata:sl-skeleton]

docs/components/spinner.md

@@ -1,16 +1,13 @@
----
-meta:
-  title: Spinner
-  description: Spinners are used to show the progress of an indeterminate operation.
-layout: component
----
+# Spinner
 
-```html:preview
+[component-header:sl-spinner]
+
+```html preview
 <sl-spinner></sl-spinner>
 ```
 
-```jsx:react
-import SlSpinner from '@shoelace-style/shoelace/dist/react/spinner';
+```jsx react
+import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlSpinner />;
 ```
@@ -21,16 +18,14 @@ const App = () => <SlSpinner />;
 
 Spinners are sized based on the current font size. To change their size, set the `font-size` property on the spinner itself or on a parent element as shown below.
 
-```html:preview
+```html preview
 <sl-spinner></sl-spinner>
 <sl-spinner style="font-size: 2rem;"></sl-spinner>
 <sl-spinner style="font-size: 3rem;"></sl-spinner>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSpinner from '@shoelace-style/shoelace/dist/react/spinner';
+```jsx react
+import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -41,20 +36,16 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Track Width
 
 The width of the spinner's track can be changed by setting the `--track-width` custom property.
 
-```html:preview
+```html preview
 <sl-spinner style="font-size: 50px; --track-width: 10px;"></sl-spinner>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSpinner from '@shoelace-style/shoelace/dist/react/spinner';
+```jsx react
+import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSpinner
@@ -66,20 +57,16 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Color
 
 The spinner's colors can be changed by setting the `--indicator-color` and `--track-color` custom properties.
 
-```html:preview
+```html preview
 <sl-spinner style="font-size: 3rem; --indicator-color: deeppink; --track-color: pink;"></sl-spinner>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSpinner from '@shoelace-style/shoelace/dist/react/spinner';
+```jsx react
+import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSpinner
@@ -92,4 +79,4 @@ const App = () => (
 );
 ```
 
-{% endraw %}
+[component-metadata:sl-spinner]

docs/components/split-panel.md

@@ -1,31 +1,26 @@
----
-meta:
-  title: Split Panel
-  description: Split panels display two adjacent panels, allowing the user to reposition them.
-layout: component
----
+# Split Panel
 
-```html:preview
+[component-header:sl-split-panel]
+
+```html preview
 <sl-split-panel>
   <div
     slot="start"
-    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     Start
   </div>
   <div
     slot="end"
-    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     End
   </div>
 </sl-split-panel>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSplitPanel from '@shoelace-style/shoelace/dist/react/split-panel';
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSplitPanel>
@@ -57,25 +52,23 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ## Examples
 
 ### Initial Position
 
 To set the initial position, use the `position` attribute. If no position is provided, it will default to 50% of the available space.
 
-```html:preview
+```html preview
 <sl-split-panel position="75">
   <div
     slot="start"
-    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     Start
   </div>
   <div
     slot="end"
-    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     End
   </div>
@@ -86,27 +79,25 @@ To set the initial position, use the `position` attribute. If no position is pro
 
 To set the initial position in pixels instead of a percentage, use the `position-in-pixels` attribute.
 
-```html:preview
+```html preview
 <sl-split-panel position-in-pixels="150">
   <div
     slot="start"
-    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     Start
   </div>
   <div
     slot="end"
-    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     End
   </div>
 </sl-split-panel>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSplitPanel from '@shoelace-style/shoelace/dist/react/split-panel';
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSplitPanel position="200">
@@ -138,33 +129,29 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Vertical
 
 Add the `vertical` attribute to render the split panel in a vertical orientation where the start and end panels are stacked. You also need to set a height when using the vertical orientation.
 
-```html:preview
+```html preview
 <sl-split-panel vertical style="height: 400px;">
   <div
     slot="start"
-    style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     Start
   </div>
   <div
     slot="end"
-    style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     End
   </div>
 </sl-split-panel>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSplitPanel from '@shoelace-style/shoelace/dist/react/split-panel';
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSplitPanel vertical style={{ height: '400px' }}>
@@ -196,24 +183,22 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Snapping
 
 To snap panels at specific positions while dragging, add the `snap` attribute with one or more space-separated values. Values must be in pixels or percentages. For example, to snap the panel at `100px` and `50%`, use `snap="100px 50%"`. You can also customize how close the divider must be before snapping with the `snap-threshold` attribute.
 
-```html:preview
+```html preview
 <div class="split-panel-snapping">
   <sl-split-panel snap="100px 50%">
     <div
       slot="start"
-      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
     >
       Start
     </div>
     <div
       slot="end"
-      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
     >
       End
     </div>
@@ -249,10 +234,8 @@ To snap panels at specific positions while dragging, add the `snap` attribute wi
 </style>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSplitPanel from '@shoelace-style/shoelace/dist/react/split-panel';
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .split-panel-snapping {
@@ -318,33 +301,29 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Disabled
 
 Add the `disabled` attribute to prevent the divider from being repositioned.
 
-```html:preview
+```html preview
 <sl-split-panel disabled>
   <div
     slot="start"
-    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     Start
   </div>
   <div
     slot="end"
-    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     End
   </div>
 </sl-split-panel>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSplitPanel from '@shoelace-style/shoelace/dist/react/split-panel';
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSplitPanel disabled>
@@ -376,26 +355,24 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Setting the Primary Panel
 
 By default, both panels will grow or shrink proportionally when the host element is resized. If a primary panel is designated, it will maintain its size and the secondary panel will grow or shrink to fit the remaining space. You can set the primary panel to `start` or `end` using the `primary` attribute.
 
 Try resizing the example below with each option and notice how the panels respond.
 
-```html:preview
+```html preview
 <div class="split-panel-primary">
   <sl-split-panel>
     <div
       slot="start"
-      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
     >
       Start
     </div>
     <div
       slot="end"
-      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
     >
       End
     </div>
@@ -417,13 +394,9 @@ Try resizing the example below with each option and notice how the panels respon
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlSplitPanel from '@shoelace-style/shoelace/dist/react/split-panel';
-import SlSelect from '@shoelace-style/shoelace/dist/react/select';
-import SlMenuItem from '@shoelace-style/shoelace/dist/react/menu-item';
+import { SlSplitPanel, SlSelect, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [primary, setPrimary] = useState('');
@@ -472,35 +445,31 @@ const App = () => {
 };
 ```
 
-{% endraw %}
-
 ### Min & Max
 
 To set a minimum or maximum size of the primary panel, use the `--min` and `--max` custom properties. Since the secondary panel is flexible, size constraints can only be applied to the primary panel. If no primary panel is designated, these constraints will be applied to the `start` panel.
 
 This examples demonstrates how you can ensure both panels are at least 150px using `--min`, `--max`, and the `calc()` function.
 
-```html:preview
+```html preview
 <sl-split-panel style="--min: 150px; --max: calc(100% - 150px);">
   <div
     slot="start"
-    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     Start
   </div>
   <div
     slot="end"
-    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     End
   </div>
 </sl-split-panel>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSplitPanel from '@shoelace-style/shoelace/dist/react/split-panel';
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSplitPanel style={{ '--min': '150px', '--max': 'calc(100% - 150px)' }}>
@@ -532,17 +501,15 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Nested Split Panels
 
 Create complex layouts that can be repositioned independently by nesting split panels.
 
-```html:preview
+```html preview
 <sl-split-panel>
   <div
     slot="start"
-    style="height: 400px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden"
+    style="height: 400px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     Start
   </div>
@@ -550,13 +517,13 @@ Create complex layouts that can be repositioned independently by nesting split p
     <sl-split-panel vertical style="height: 400px;">
       <div
         slot="start"
-        style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden"
+        style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
       >
         Top
       </div>
       <div
         slot="end"
-        style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden"
+        style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
       >
         Bottom
       </div>
@@ -565,10 +532,8 @@ Create complex layouts that can be repositioned independently by nesting split p
 </sl-split-panel>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSplitPanel from '@shoelace-style/shoelace/dist/react/split-panel';
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSplitPanel>
@@ -616,35 +581,30 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Customizing the Divider
 
 You can target the `divider` part to apply CSS properties to the divider. To add a custom handle, slot an icon into the `divider` slot. When customizing the divider, make sure to think about focus styles for keyboard users.
 
-```html:preview
+```html preview
 <sl-split-panel style="--divider-width: 20px;">
   <sl-icon slot="divider" name="grip-vertical"></sl-icon>
   <div
     slot="start"
-    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     Start
   </div>
   <div
     slot="end"
-    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
   >
     End
   </div>
 </sl-split-panel>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSplitPanel from '@shoelace-style/shoelace/dist/react/split-panel';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlSplitPanel, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSplitPanel style={{ '--divider-width': '20px' }}>
@@ -677,23 +637,21 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 Here's a more elaborate example that changes the divider's color and width and adds a styled handle.
 
-```html:preview
+```html preview
 <div class="split-panel-divider">
   <sl-split-panel>
     <sl-icon slot="divider" name="grip-vertical"></sl-icon>
     <div
       slot="start"
-      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
     >
       Start
     </div>
     <div
       slot="end"
-      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center; overflow: hidden;"
+      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
     >
       End
     </div>
@@ -728,11 +686,8 @@ Here's a more elaborate example that changes the divider's color and width and a
 </style>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSplitPanel from '@shoelace-style/shoelace/dist/react/split-panel';
-import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
+```jsx react
+import { SlSplitPanel, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .split-panel-divider sl-split-panel {
@@ -798,4 +753,4 @@ const App = () => (
 );
 ```
 
-{% endraw %}
+[component-metadata:sl-split-panel]

docs/components/switch.md

@@ -1,23 +1,18 @@
----
-meta:
-  title: Switch
-  description: Switches allow the user to toggle an option on or off.
-layout: component
----
+# Switch
 
-```html:preview
+[component-header:sl-switch]
+
+```html preview
 <sl-switch>Switch</sl-switch>
 ```
 
-```jsx:react
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
+```jsx react
+import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlSwitch>Switch</SlSwitch>;
 ```
 
-:::tip
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
-:::
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
@@ -25,12 +20,12 @@ This component works with standard `<form>` elements. Please refer to the sectio
 
 Use the `checked` attribute to activate the switch.
 
-```html:preview
+```html preview
 <sl-switch checked>Checked</sl-switch>
 ```
 
-```jsx:react
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
+```jsx react
+import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlSwitch checked>Checked</SlSwitch>;
 ```
@@ -39,21 +34,21 @@ const App = () => <SlSwitch checked>Checked</SlSwitch>;
 
 Use the `disabled` attribute to disable the switch.
 
-```html:preview
+```html preview
 <sl-switch disabled>Disabled</sl-switch>
 ```
 
-```jsx:react
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
+```jsx react
+import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlSwitch disabled>Disabled</SlSwitch>;
 ```
 
-### Sizes
+## Sizes
 
 Use the `size` attribute to change a switch's size.
 
-```html:preview
+```html preview
 <sl-switch size="small">Small</sl-switch>
 <br />
 <sl-switch size="medium">Medium</sl-switch>
@@ -61,8 +56,8 @@ Use the `size` attribute to change a switch's size.
 <sl-switch size="large">Large</sl-switch>
 ```
 
-```jsx:react
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
+```jsx react
+import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -79,14 +74,12 @@ const App = () => (
 
 Use the available custom properties to change how the switch is styled.
 
-```html:preview
+```html preview
 <sl-switch style="--width: 80px; --height: 40px; --thumb-size: 36px;">Really big</sl-switch>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
+```jsx react
+import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSwitch
@@ -99,4 +92,4 @@ const App = () => (
 );
 ```
 
-{% endraw %}
+[component-metadata:sl-switch]

docs/components/tab-group.md

@@ -1,13 +1,10 @@
----
-meta:
-  title: Tab Group
-  description: Tab groups organize content into a container that shows one section at a time.
-layout: component
----
+# Tab Group
+
+[component-header:sl-tab-group]
 
 Tab groups make use of [tabs](/components/tab) and [tab panels](/components/tab-panel). Each tab must be slotted into the `nav` slot and its `panel` must refer to a tab panel of the same name.
 
-```html:preview
+```html preview
 <sl-tab-group>
   <sl-tab slot="nav" panel="general">General</sl-tab>
   <sl-tab slot="nav" panel="custom">Custom</sl-tab>
@@ -21,10 +18,8 @@ Tab groups make use of [tabs](/components/tab) and [tab panels](/components/tab-
 </sl-tab-group>
 ```
 
-```jsx:react
-import SlTab from '@shoelace-style/shoelace/dist/react/tab';
-import SlTabGroup from '@shoelace-style/shoelace/dist/react/tab-group';
-import SlTabPanel from '@shoelace-style/shoelace/dist/react/tab-panel';
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTabGroup>
@@ -55,7 +50,7 @@ const App = () => (
 
 Tabs can be shown on the bottom by setting `placement` to `bottom`.
 
-```html:preview
+```html preview
 <sl-tab-group placement="bottom">
   <sl-tab slot="nav" panel="general">General</sl-tab>
   <sl-tab slot="nav" panel="custom">Custom</sl-tab>
@@ -69,10 +64,8 @@ Tabs can be shown on the bottom by setting `placement` to `bottom`.
 </sl-tab-group>
 ```
 
-```jsx:react
-import SlTab from '@shoelace-style/shoelace/dist/react/tab';
-import SlTabGroup from '@shoelace-style/shoelace/dist/react/tab-group';
-import SlTabPanel from '@shoelace-style/shoelace/dist/react/tab-panel';
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTabGroup placement="bottom">
@@ -101,7 +94,7 @@ const App = () => (
 
 Tabs can be shown on the starting side by setting `placement` to `start`.
 
-```html:preview
+```html preview
 <sl-tab-group placement="start">
   <sl-tab slot="nav" panel="general">General</sl-tab>
   <sl-tab slot="nav" panel="custom">Custom</sl-tab>
@@ -115,10 +108,8 @@ Tabs can be shown on the starting side by setting `placement` to `start`.
 </sl-tab-group>
 ```
 
-```jsx:react
-import SlTab from '@shoelace-style/shoelace/dist/react/tab';
-import SlTabGroup from '@shoelace-style/shoelace/dist/react/tab-group';
-import SlTabPanel from '@shoelace-style/shoelace/dist/react/tab-panel';
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTabGroup placement="start">
@@ -147,7 +138,7 @@ const App = () => (
 
 Tabs can be shown on the ending side by setting `placement` to `end`.
 
-```html:preview
+```html preview
 <sl-tab-group placement="end">
   <sl-tab slot="nav" panel="general">General</sl-tab>
   <sl-tab slot="nav" panel="custom">Custom</sl-tab>
@@ -161,10 +152,8 @@ Tabs can be shown on the ending side by setting `placement` to `end`.
 </sl-tab-group>
 ```
 
-```jsx:react
-import SlTab from '@shoelace-style/shoelace/dist/react/tab';
-import SlTabGroup from '@shoelace-style/shoelace/dist/react/tab-group';
-import SlTabPanel from '@shoelace-style/shoelace/dist/react/tab-panel';
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTabGroup placement="end">
@@ -193,7 +182,7 @@ const App = () => (
 
 Add the `closable` attribute to a tab to show a close button. This example shows how you can dynamically remove tabs from the DOM when the close button is activated.
 
-```html:preview
+```html preview
 <sl-tab-group class="tabs-closable">
   <sl-tab slot="nav" panel="general">General</sl-tab>
   <sl-tab slot="nav" panel="closable-1" closable>Closable 1</sl-tab>
@@ -225,10 +214,8 @@ Add the `closable` attribute to a tab to show a close button. This example shows
 </script>
 ```
 
-```jsx:react
-import SlTab from '@shoelace-style/shoelace/dist/react/tab';
-import SlTabGroup from '@shoelace-style/shoelace/dist/react/tab-group';
-import SlTabPanel from '@shoelace-style/shoelace/dist/react/tab-panel';
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   function handleClose(event) {
@@ -273,7 +260,7 @@ const App = () => {
 
 When there are more tabs than horizontal space allows, the nav will be scrollable.
 
-```html:preview
+```html preview
 <sl-tab-group>
   <sl-tab slot="nav" panel="tab-1">Tab 1</sl-tab>
   <sl-tab slot="nav" panel="tab-2">Tab 2</sl-tab>
@@ -319,10 +306,8 @@ When there are more tabs than horizontal space allows, the nav will be scrollabl
 </sl-tab-group>
 ```
 
-```jsx:react
-import SlTab from '@shoelace-style/shoelace/dist/react/tab';
-import SlTabGroup from '@shoelace-style/shoelace/dist/react/tab-group';
-import SlTabPanel from '@shoelace-style/shoelace/dist/react/tab-panel';
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTabGroup>
@@ -413,9 +398,9 @@ const App = () => (
 
 ### Manual Activation
 
-When focused, keyboard users can press [[Left]] or [[Right]] to select the desired tab. By default, the corresponding tab panel will be shown immediately (automatic activation). You can change this behavior by setting `activation="manual"` which will require the user to press [[Space]] or [[Enter]] before showing the tab panel (manual activation).
+When focused, keyboard users can press <kbd>Left</kbd> or <kbd>Right</kbd> to select the desired tab. By default, the corresponding tab panel will be shown immediately (automatic activation). You can change this behavior by setting `activation="manual"` which will require the user to press <kbd>Space</kbd> or <kbd>Enter</kbd> before showing the tab panel (manual activation).
 
-```html:preview
+```html preview
 <sl-tab-group activation="manual">
   <sl-tab slot="nav" panel="general">General</sl-tab>
   <sl-tab slot="nav" panel="custom">Custom</sl-tab>
@@ -429,10 +414,8 @@ When focused, keyboard users can press [[Left]] or [[Right]] to select the desir
 </sl-tab-group>
 ```
 
-```jsx:react
-import SlTab from '@shoelace-style/shoelace/dist/react/tab';
-import SlTabGroup from '@shoelace-style/shoelace/dist/react/tab-group';
-import SlTabPanel from '@shoelace-style/shoelace/dist/react/tab-panel';
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTabGroup activation="manual">
@@ -456,3 +439,5 @@ const App = () => (
   </SlTabGroup>
 );
 ```
+
+[component-metadata:sl-tab-group]

docs/components/tab-panel.md

@@ -1,11 +1,8 @@
----
-meta:
-  title: Tab Panel
-  description: Tab panels are used inside tab groups to display tabbed content.
-layout: component
----
+# Tab Panel
 
-```html:preview
+[component-header:sl-tab-panel]
+
+```html preview
 <sl-tab-group>
   <sl-tab slot="nav" panel="general">General</sl-tab>
   <sl-tab slot="nav" panel="custom">Custom</sl-tab>
@@ -19,10 +16,8 @@ layout: component
 </sl-tab-group>
 ```
 
-```jsx:react
-import SlTab from '@shoelace-style/shoelace/dist/react/tab';
-import SlTabGroup from '@shoelace-style/shoelace/dist/react/tab-group';
-import SlTabPanel from '@shoelace-style/shoelace/dist/react/tab-panel';
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTabGroup>
@@ -47,6 +42,6 @@ const App = () => (
 );
 ```
 
-:::tip
-Additional demonstrations can be found in the [tab group examples](/components/tab-group).
-:::
+?> Additional demonstrations can be found in the [tab group examples](/components/tab-group).
+
+[component-metadata:sl-tab-panel]

docs/components/tab.md

@@ -0,0 +1,27 @@
+# Tab
+
+[component-header:sl-tab]
+
+```html preview
+<sl-tab>Tab</sl-tab>
+<sl-tab active>Active</sl-tab>
+<sl-tab closable>Closable</sl-tab>
+<sl-tab disabled>Disabled</sl-tab>
+```
+
+```jsx react
+import { SlTab } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlTab>Tab</SlTab>
+    <SlTab active>Active</SlTab>
+    <SlTab closable>Closable</SlTab>
+    <SlTab disabled>Disabled</SlTab>
+  </>
+);
+```
+
+?> Additional demonstrations can be found in the [tab group examples](/components/tab-group).
+
+[component-metadata:sl-tab]

docs/components/tag.md

@@ -1,11 +1,8 @@
----
-meta:
-  title: Tag
-  description: Tags are used as labels to organize things or to indicate a selection.
-layout: component
----
+# Tag
 
-```html:preview
+[component-header:sl-tag]
+
+```html preview
 <sl-tag variant="primary">Primary</sl-tag>
 <sl-tag variant="success">Success</sl-tag>
 <sl-tag variant="neutral">Neutral</sl-tag>
@@ -13,8 +10,8 @@ layout: component
 <sl-tag variant="danger">Danger</sl-tag>
 ```
 
-```jsx:react
-import SlTag from '@shoelace-style/shoelace/dist/react/tag';
+```jsx react
+import { SlTag } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -33,14 +30,14 @@ const App = () => (
 
 Use the `size` attribute to change a tab's size.
 
-```html:preview
+```html preview
 <sl-tag size="small">Small</sl-tag>
 <sl-tag size="medium">Medium</sl-tag>
 <sl-tag size="large">Large</sl-tag>
 ```
 
-```jsx:react
-import SlTag from '@shoelace-style/shoelace/dist/react/tag';
+```jsx react
+import { SlTag } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -55,14 +52,14 @@ const App = () => (
 
 Use the `pill` attribute to give tabs rounded edges.
 
-```html:preview
+```html preview
 <sl-tag size="small" pill>Small</sl-tag>
 <sl-tag size="medium" pill>Medium</sl-tag>
 <sl-tag size="large" pill>Large</sl-tag>
 ```
 
-```jsx:react
-import SlTag from '@shoelace-style/shoelace/dist/react/tag';
+```jsx react
+import { SlTag } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -83,7 +80,7 @@ const App = () => (
 
 Use the `removable` attribute to add a remove button to the tag.
 
-```html:preview
+```html preview
 <div class="tags-removable">
   <sl-tag size="small" removable>Small</sl-tag>
   <sl-tag size="medium" removable>Medium</sl-tag>
@@ -107,8 +104,8 @@ Use the `removable` attribute to add a remove button to the tag.
 </style>
 ```
 
-```jsx:react
-import SlTag from '@shoelace-style/shoelace/dist/react/tag';
+```jsx react
+import { SlTag } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .tags-removable sl-tag {
@@ -144,3 +141,5 @@ const App = () => {
   );
 };
 ```
+
+[component-metadata:sl-tag]

docs/components/textarea.md

@@ -1,23 +1,18 @@
----
-meta:
-  title: Textarea
-  description: Textareas collect data from the user and allow multiple lines of text.
-layout: component
----
+# Textarea
 
-```html:preview
+[component-header:sl-textarea]
+
+```html preview
 <sl-textarea></sl-textarea>
 ```
 
-```jsx:react
-import SlTextarea from '@shoelace-style/shoelace/dist/react/textarea';
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlTextarea />;
 ```
 
-:::tip
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
-:::
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
@@ -25,12 +20,12 @@ This component works with standard `<form>` elements. Please refer to the sectio
 
 Use the `label` attribute to give the textarea an accessible label. For labels that contain HTML, use the `label` slot instead.
 
-```html:preview
+```html preview
 <sl-textarea label="Comments"></sl-textarea>
 ```
 
-```jsx:react
-import SlTextarea from '@shoelace-style/shoelace/dist/react/textarea';
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlTextarea label="Comments" />;
 ```
@@ -39,12 +34,12 @@ const App = () => <SlTextarea label="Comments" />;
 
 Add descriptive help text to a textarea with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
 
-```html:preview
+```html preview
 <sl-textarea label="Feedback" help-text="Please tell us what you think."> </sl-textarea>
 ```
 
-```jsx:react
-import SlTextarea from '@shoelace-style/shoelace/dist/react/textarea';
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlTextarea label="Feedback" help-text="Please tell us what you think." />;
 ```
@@ -53,12 +48,12 @@ const App = () => <SlTextarea label="Feedback" help-text="Please tell us what yo
 
 Use the `rows` attribute to change the number of text rows that get shown.
 
-```html:preview
+```html preview
 <sl-textarea rows="2"></sl-textarea>
 ```
 
-```jsx:react
-import SlTextarea from '@shoelace-style/shoelace/dist/react/textarea';
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlTextarea rows={2} />;
 ```
@@ -67,12 +62,12 @@ const App = () => <SlTextarea rows={2} />;
 
 Use the `placeholder` attribute to add a placeholder.
 
-```html:preview
+```html preview
 <sl-textarea placeholder="Type something"></sl-textarea>
 ```
 
-```jsx:react
-import SlTextarea from '@shoelace-style/shoelace/dist/react/textarea';
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlTextarea placeholder="Type something" />;
 ```
@@ -81,12 +76,12 @@ const App = () => <SlTextarea placeholder="Type something" />;
 
 Add the `filled` attribute to draw a filled textarea.
 
-```html:preview
+```html preview
 <sl-textarea placeholder="Type something" filled></sl-textarea>
 ```
 
-```jsx:react
-import SlTextarea from '@shoelace-style/shoelace/dist/react/textarea';
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlTextarea placeholder="Type something" filled />;
 ```
@@ -95,12 +90,12 @@ const App = () => <SlTextarea placeholder="Type something" filled />;
 
 Use the `disabled` attribute to disable a textarea.
 
-```html:preview
+```html preview
 <sl-textarea placeholder="Textarea" disabled></sl-textarea>
 ```
 
-```jsx:react
-import SlTextarea from '@shoelace-style/shoelace/dist/react/textarea';
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlTextarea placeholder="Textarea" disabled />;
 ```
@@ -109,7 +104,7 @@ const App = () => <SlTextarea placeholder="Textarea" disabled />;
 
 Use the `size` attribute to change a textarea's size.
 
-```html:preview
+```html preview
 <sl-textarea placeholder="Small" size="small"></sl-textarea>
 <br />
 <sl-textarea placeholder="Medium" size="medium"></sl-textarea>
@@ -117,8 +112,8 @@ Use the `size` attribute to change a textarea's size.
 <sl-textarea placeholder="Large" size="large"></sl-textarea>
 ```
 
-```jsx:react
-import SlTextarea from '@shoelace-style/shoelace/dist/react/textarea';
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
@@ -135,12 +130,12 @@ const App = () => (
 
 By default, textareas can be resized vertically by the user. To prevent resizing, set the `resize` attribute to `none`.
 
-```html:preview
+```html preview
 <sl-textarea resize="none"></sl-textarea>
 ```
 
-```jsx:react
-import SlTextarea from '@shoelace-style/shoelace/dist/react/textarea';
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlTextarea resize="none" />;
 ```
@@ -149,12 +144,14 @@ const App = () => <SlTextarea resize="none" />;
 
 Textareas will automatically resize to expand to fit their content when `resize` is set to `auto`.
 
-```html:preview
+```html preview
 <sl-textarea resize="auto"></sl-textarea>
 ```
 
-```jsx:react
-import SlTextarea from '@shoelace-style/shoelace/dist/react/textarea';
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => <SlTextarea resize="auto" />;
 ```
+
+[component-metadata:sl-textarea]

docs/components/tooltip.md

@@ -1,23 +1,19 @@
----
-meta:
-  title: Tooltip
-  description: Tooltips display additional information based on a specific action.
-layout: component
----
+# Tooltip
+
+[component-header:sl-tooltip]
 
 A tooltip's target is its _first child element_, so you should only wrap one element inside of the tooltip. If you need the tooltip to show up for multiple elements, nest them inside a container first.
 
 Tooltips use `display: contents` so they won't interfere with how elements are positioned in a flex or grid layout.
 
-```html:preview
+```html preview
 <sl-tooltip content="This is a tooltip">
   <sl-button>Hover Me</sl-button>
 </sl-tooltip>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlTooltip from '@shoelace-style/shoelace/dist/react/tooltip';
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTooltip content="This is a tooltip">
@@ -32,7 +28,7 @@ const App = () => (
 
 Use the `placement` attribute to set the preferred placement of the tooltip.
 
-```html:preview
+```html preview
 <div class="tooltip-placement-example">
   <div class="tooltip-placement-example-row">
     <sl-tooltip content="top-start" placement="top-start">
@@ -125,9 +121,8 @@ Use the `placement` attribute to set the preferred placement of the tooltip.
 </style>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlTooltip from '@shoelace-style/shoelace/dist/react/tooltip';
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .tooltip-placement-example {
@@ -230,15 +225,14 @@ const App = () => (
 
 Set the `trigger` attribute to `click` to toggle the tooltip on click instead of hover.
 
-```html:preview
+```html preview
 <sl-tooltip content="Click again to dismiss" trigger="click">
   <sl-button>Click to Toggle</sl-button>
 </sl-tooltip>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlTooltip from '@shoelace-style/shoelace/dist/react/tooltip';
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTooltip content="Click again to dismiss" trigger="click">
@@ -251,7 +245,7 @@ const App = () => (
 
 Tooltips can be controller programmatically by setting the `trigger` attribute to `manual`. Use the `open` attribute to control when the tooltip is shown.
 
-```html:preview
+```html preview
 <sl-button style="margin-right: 4rem;">Toggle Manually</sl-button>
 
 <sl-tooltip content="This is an avatar" trigger="manual" class="manual-tooltip">
@@ -266,13 +260,9 @@ Tooltips can be controller programmatically by setting the `trigger` attribute t
 </script>
 ```
 
-{% raw %}
-
-```jsx:react
+```jsx react
 import { useState } from 'react';
-import SlAvatar from '@shoelace-style/shoelace/dist/react/avatar';
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlTooltip from '@shoelace-style/shoelace/dist/react/tooltip';
+import { SlAvatar, SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [open, setOpen] = useState(false);
@@ -291,23 +281,18 @@ const App = () => {
 };
 ```
 
-{% endraw %}
-
 ### Removing Arrows
 
 You can control the size of tooltip arrows by overriding the `--sl-tooltip-arrow-size` design token. To remove them, set the value to `0` as shown below.
 
-```html:preview
+```html preview
 <sl-tooltip content="This is a tooltip" style="--sl-tooltip-arrow-size: 0;">
   <sl-button>No Arrow</sl-button>
 </sl-tooltip>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlTooltip from '@shoelace-style/shoelace/dist/react/tooltip';
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <div style={{ '--sl-tooltip-arrow-size': '0' }}>
@@ -322,8 +307,6 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 To override it globally, set it in a root block in your stylesheet after the Shoelace stylesheet is loaded.
 
 ```css
@@ -336,7 +319,7 @@ To override it globally, set it in a root block in your stylesheet after the Sho
 
 Use the `content` slot to create tooltips with HTML content. Tooltips are designed only for text and presentational elements. Avoid placing interactive content, such as buttons, links, and form controls, in a tooltip.
 
-```html:preview
+```html preview
 <sl-tooltip>
   <div slot="content">I'm not <strong>just</strong> a tooltip, I'm a <em>tooltip</em> with HTML!</div>
 
@@ -344,9 +327,8 @@ Use the `content` slot to create tooltips with HTML content. Tooltips are design
 </sl-tooltip>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlTooltip from '@shoelace-style/shoelace/dist/react/tooltip';
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTooltip>
@@ -363,17 +345,14 @@ const App = () => (
 
 Use the `--max-width` custom property to change the width the tooltip can grow to before wrapping occurs.
 
-```html:preview
+```html preview
 <sl-tooltip style="--max-width: 80px;" content="This tooltip will wrap after only 80 pixels.">
   <sl-button>Hover me</sl-button>
 </sl-tooltip>
 ```
 
-{% raw %}
-
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlTooltip from '@shoelace-style/shoelace/dist/react/tooltip';
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTooltip style={{ '--max-width': '80px' }} content="This tooltip will wrap after only 80 pixels.">
@@ -382,13 +361,11 @@ const App = () => (
 );
 ```
 
-{% endraw %}
-
 ### Hoisting
 
-Tooltips will be clipped if they're inside a container that has `overflow: auto|hidden|scroll`. The `hoist` attribute forces the tooltip to use a fixed positioning strategy, allowing it to break out of the container. In this case, the tooltip will be positioned relative to its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
+Tooltips will be clipped if they're inside a container that has `overflow: auto|hidden|scroll`. The `hoist` attribute forces the tooltip to use a fixed positioning strategy, allowing it to break out of the container. In this case, the tooltip will be positioned relative to its containing block, which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
 
-```html:preview
+```html preview
 <div class="tooltip-hoist">
   <sl-tooltip content="This is a tooltip">
     <sl-button>No Hoist</sl-button>
@@ -409,9 +386,8 @@ Tooltips will be clipped if they're inside a container that has `overflow: auto|
 </style>
 ```
 
-```jsx:react
-import SlButton from '@shoelace-style/shoelace/dist/react/button';
-import SlTooltip from '@shoelace-style/shoelace/dist/react/tooltip';
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .tooltip-hoist {
@@ -438,3 +414,5 @@ const App = () => (
   </>
 );
 ```
+
+[component-metadata:sl-tooltip]