From 68b982a74449dc775ddd3e1b0fd27eba23730d4b Mon Sep 17 00:00:00 2001 From: konnorrogers Date: Mon, 12 Jun 2023 12:48:15 -0400 Subject: [PATCH] update docs --- cspell.json | 1 + docs/_includes/component.njk | 18 ++++---- docs/assets/scripts/code-previews.js | 6 +-- docs/pages/frameworks/angular.md | 4 +- docs/pages/frameworks/react.md | 4 +- docs/pages/frameworks/vue-2.md | 4 +- docs/pages/frameworks/vue.md | 4 +- docs/pages/getting-started/installation.md | 48 ++++++++++++++++------ docs/pages/getting-started/themes.md | 4 +- docs/pages/index.md | 6 +-- 10 files changed, 61 insertions(+), 38 deletions(-) diff --git a/cspell.json b/cspell.json index bc92397a..6ca3c963 100644 --- a/cspell.json +++ b/cspell.json @@ -18,6 +18,7 @@ "CACHEABLE", "callout", "callouts", + "cdndir", "chatbubble", "checkmark", "claviska", diff --git a/docs/_includes/component.njk b/docs/_includes/component.njk index 8d65f7f8..d353b988 100644 --- a/docs/_includes/component.njk +++ b/docs/_includes/component.njk @@ -39,15 +39,15 @@ {% if component.summary %} {{ component.summary | markdownInline | safe }} {% endif %} -

- +

+ {# Markdown content #} {{ content | safe }} {# Importing #}

Importing

- If you're using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use + 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 this component.

@@ -59,18 +59,18 @@

- To import this component from the CDN + To import this component from the CDN using a script tag:

- 
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@{{ meta.version }}/dist/{{ component.path }}"></script>
+ 
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@{{ meta.version }}/cdn/{{ component.path }}"></script>

- To import this component from the CDN + To import this component from the CDN using a JavaScript import:

- 
import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@{{ meta.version }}/dist/{{ component.path }}';
+ 
import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@{{ meta.version }}/cdn/{{ component.path }}';
 @@ -337,11 +337,11 @@

Dependencies

This component automatically imports the following dependencies.

- + {% endif %} -{% endblock %} \ No newline at end of file +{% endblock %} diff --git a/docs/assets/scripts/code-previews.js b/docs/assets/scripts/code-previews.js index 40e11aa7..b7c26233 100644 --- a/docs/assets/scripts/code-previews.js +++ b/docs/assets/scripts/code-previews.js @@ -180,7 +180,7 @@ // HTML templates if (!isReact) { htmlTemplate = - `\n` + + `\n` + `\n${htmlExample}`; jsTemplate = ''; } @@ -191,7 +191,7 @@ 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@${shoelaceVersion}/dist/utilities/base-path';\n` + + `import { setBasePath } from 'https://cdn.skypack.dev/@shoelace-style/shoelace@${shoelaceVersion}/cdn/utilities/base-path';\n` + `\n` + `// Set the base path for Shoelace assets\n` + `setBasePath('https://cdn.skypack.dev/@shoelace-style/shoelace@${shoelaceVersion}/dist/')\n` + @@ -202,7 +202,7 @@ // CSS templates cssTemplate = - `@import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${shoelaceVersion}/dist/themes/${ + `@import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${shoelaceVersion}/cdn/themes/${ isDark ? 'dark' : 'light' }.css';\n` + '\n' + diff --git a/docs/pages/frameworks/angular.md b/docs/pages/frameworks/angular.md index e604d484..b1ce5675 100644 --- a/docs/pages/frameworks/angular.md +++ b/docs/pages/frameworks/angular.md @@ -22,7 +22,7 @@ Next, [include a theme](/getting-started/themes) and set the [base path](/gettin import '@shoelace-style/shoelace/dist/themes/light.css'; import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path'; -setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/'); +setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/'); ``` :::tip @@ -85,4 +85,4 @@ Now you can start using Shoelace components in your app! :::tip Are you using Shoelace with Angular? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/angular.md) -::: +::: \ No newline at end of file diff --git a/docs/pages/frameworks/react.md b/docs/pages/frameworks/react.md index a46a2091..bab6d59e 100644 --- a/docs/pages/frameworks/react.md +++ b/docs/pages/frameworks/react.md @@ -23,7 +23,7 @@ Next, [include a theme](/getting-started/themes) and set the [base path](/gettin import '@shoelace-style/shoelace/dist/themes/light.css'; import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path'; -setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/'); +setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/'); ``` :::tip @@ -151,4 +151,4 @@ For more details, refer to Jest's [`transformIgnorePatterns` customization](http :::tip Are you using Shoelace with React? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/react.md) -::: +::: \ No newline at end of file diff --git a/docs/pages/frameworks/vue-2.md b/docs/pages/frameworks/vue-2.md index 45842ac5..c099c5de 100644 --- a/docs/pages/frameworks/vue-2.md +++ b/docs/pages/frameworks/vue-2.md @@ -26,7 +26,7 @@ Next, [include a theme](/getting-started/themes) and set the [base path](/gettin import '@shoelace-style/shoelace/dist/themes/light.css'; import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path'; -setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/'); +setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/'); ``` :::tip @@ -104,4 +104,4 @@ Now you can use the `v-sl-model` directive to keep your data in sync! :::tip Are you using Shoelace with Vue? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue-2.md) -::: +::: \ No newline at end of file diff --git a/docs/pages/frameworks/vue.md b/docs/pages/frameworks/vue.md index 88062b0c..3284a44f 100644 --- a/docs/pages/frameworks/vue.md +++ b/docs/pages/frameworks/vue.md @@ -26,7 +26,7 @@ Next, [include a theme](/getting-started/themes) and set the [base path](/gettin import '@shoelace-style/shoelace/dist/themes/light.css'; import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path'; -setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/'); +setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/cdn/'); ``` :::tip @@ -124,4 +124,4 @@ Here is an example: Close -``` +``` \ No newline at end of file diff --git a/docs/pages/getting-started/installation.md b/docs/pages/getting-started/installation.md index 6b423530..a1441dfa 100644 --- a/docs/pages/getting-started/installation.md +++ b/docs/pages/getting-started/installation.md @@ -22,8 +22,8 @@ While convenient, autoloading may lead to a [Flash of Undefined Custom Elements] ```html - - + + ``` @@ -33,8 +33,8 @@ While convenient, autoloading may lead to a [Flash of Undefined Custom Elements] The traditional CDN loader registers all Shoelace elements up front. Note that, if you're only using a handful of components, it will be much more efficient to stick with the autoloader. However, you can also [cherry pick](#cherry-picking) components if you want to load specific ones up front. ```html - - + + ``` @@ -45,7 +45,7 @@ The traditional CDN loader registers all Shoelace elements up front. Note that, The code above will load the light theme. If you want to use the [dark theme](/getting-started/themes#dark-theme) instead, update the stylesheet as shown below and add `` to your page. ```html - + ``` ### Light & Dark Theme @@ -56,21 +56,21 @@ If you want to load the light or dark theme based on the user's `prefers-color-s ``` Now you can [start using Shoelace!](/getting-started/usage) -## Local Installation +## NPM installation -If you don't want to use the CDN, you can install Shoelace locally with the following command. +If you don't want to use the CDN, you can install Shoelace from NPM with the following command. ```bash npm install @shoelace-style/shoelace @@ -110,20 +110,26 @@ However, if you're [cherry picking](#cherry-picking) or [bundling](#bundling) Sh ``` :::tip -The library also exports a `getBasePath()` method you can use to reference assets. +When setting a basePath, and easy way to check if it was down properly is by checking if an icon exists. + +For example, if I set the basePath to `/dist`, I should be able to go to: + +`https:///dist/assets/icons/arrow-left.svg` and the browser should show me the SVG. + +Shoelace also exports a `getBasePath()` method you can use to reference assets. ::: ## Cherry Picking -Cherry picking can be done from [the CDN](#cdn-installation-easiest) or your [local installation](#local-installation). This approach will load only the components you need up front, while limiting the number of files the browser has to download. The disadvantage is that you need to import each individual component. +Cherry picking can be done from [the CDN](#cdn-installation-easiest) or from [NPM](#npm-installation). This approach will load only the components you need up front, while limiting the number of files the browser has to download. The disadvantage is that you need to import each individual component. Here's an example that loads only the button component. Again, if you're not using a module resolver, you'll need to adjust the path to point to the folder Shoelace is in. ```html - + @@ -173,3 +179,19 @@ setBasePath('/path/to/shoelace/dist'); :::warning Component modules include side effects for registration purposes. Because of this, importing directly from `@shoelace-style/shoelace` may result in a larger bundle size than necessary. For optimal tree shaking, always cherry pick, i.e. import components and utilities from their respective files, as shown above. ::: + +## The difference between CDN and NPM + +You'll notice above that the CDN links all start with `/cdn/` and imports using NPM use `/dist/`. +The `/cdn` files use a different bundle from `/dist`. `/cdn` files come "prebundled" which means all dependencies are +inlined so you do not need to worry about loading any additional libraries. `/dist` does **NOT** prebundle dependencies +allowing for your bundler of choice to more efficiently deduplicate dependencies resulting in smaller overall bundles +and greater code sharing. + +TLDR: + +- `@shoelace-style/shoelace/cdn` is for CDN +- `@shoelace-style/shoelace/dist` is for NPM + +This change was introduced in `v2.5.0` to address issues around installations from NPM +loading multiple versions of libraries such as the Lit web component library which Shoelace uses internally. \ No newline at end of file diff --git a/docs/pages/getting-started/themes.md b/docs/pages/getting-started/themes.md index 1dd1508c..da35aa93 100644 --- a/docs/pages/getting-started/themes.md +++ b/docs/pages/getting-started/themes.md @@ -127,7 +127,7 @@ The dark theme works by taking the light theme's [color tokens](/tokens/color) a To install the dark theme, add the following to the `` section of your page. ```html - + ``` To activate the theme, apply the `sl-theme-dark` class to the `` element. @@ -146,4 +146,4 @@ Shoelace doesn't try to auto-detect the user's light/dark mode preference. This - Allow the user to override the setting in your app - Remember the user's preference and restore it on subsequent logins -Shoelace avoids using the `prefers-color-scheme` media query because not all apps support dark mode, and it would break things for the ones that don't. +Shoelace avoids using the `prefers-color-scheme` media query because not all apps support dark mode, and it would break things for the ones that don't. \ No newline at end of file diff --git a/docs/pages/index.md b/docs/pages/index.md index e9bf8fbc..c59e01d9 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -41,8 +41,8 @@ Add the following code to your page. ```html - - + + ``` Now you have access to all of Shoelace's components! Try adding a button: @@ -137,4 +137,4 @@ Special thanks to the following projects and individuals that help make Shoelace - Positioning of dropdowns, tooltips, et al is handled by [Floating UI](https://floating-ui.com/) - Animations are courtesy of [animate.css](https://animate.style/) - Search is powered by [Lunr](https://lunrjs.com/) -- The Shoelace logo was designed with a single shoelace by [Adam K Olson](https://twitter.com/adamkolson) +- The Shoelace logo was designed with a single shoelace by [Adam K Olson](https://twitter.com/adamkolson) \ No newline at end of file