add importing section to docs

shoelace-style · Sep 9, 2021 · 5749476 · 5749476
1 parent 5b1b704
commit 5749476
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 1 deletion.
diff --git a/docs/assets/plugins/metadata/metadata.js b/docs/assets/plugins/metadata/metadata.js
@@ -255,6 +255,9 @@
     metadata.modules?.map(module => {
       module.declarations?.map(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);
         }
       });
@@ -429,6 +432,41 @@
           `;
         }
 
+        if (component.path) {
+          /* prettier-ignore */
+          result += `
+            ## Importing
+
+            <sl-tab-group>
+            <sl-tab slot="nav" panel="cdn" active>CDN</sl-tab>
+            <sl-tab slot="nav" panel="bundler">Bundler</sl-tab>
+            <sl-tab slot="nav" panel="react">React</sl-tab>
+
+            <sl-tab-panel name="cdn">\n
+            To import this component from [the CDN](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace):
+
+            \`\`\`js
+            import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${metadata.package.version}/${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/${component.path}';
+            \`\`\`
+            </sl-tab-panel>
+
+            <sl-tab-panel name="react">\n
+            To import this component using [\`@shoelace-style/react\`](https://www.npmjs.com/package/@shoelace-style/react):
+            \`\`\`js
+            import '@shoelace-style/react/dist/${component.tagName.replace(/^sl-/, '')}';
+            \`\`\`
+            </sl-tab-panel>
+            </sl-tab-group>
+          `;
+        }
+
         // Strip whitespace so markdown doesn't process things as code blocks
         return result.replace(/^ +| +$/gm, '');
       });

diff --git a/docs/assets/styles/docs.css b/docs/assets/styles/docs.css
@@ -318,6 +318,10 @@ strong {
   margin-bottom: 0;
 }
 
+.markdown-section sl-tab-panel::part(base) {
+  padding: var(--sl-spacing-medium) 0;
+}
+
 .docsify-pagination-container {
   border-top-color: rgb(var(--sl-color-neutral-200)) !important;
 }

diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -94,7 +94,7 @@ Here's an example that loads only the button component. Again, if you're not usi
 </script>
 ```
 
-Some components have dependencies that are automatically imported when you cherry pick. If a component has dependencies, they will be listed in the "Dependencies" section of the component's documentation.
+You can copy and paste the code to import a component from the "Importing" section of the component's documentation. Note that some components have dependencies that are automatically imported when you cherry pick. If a component has dependencies, they will be listed in the "Dependencies" section of its docs.
 
 !> Never cherry pick components or utilities from `shoelace.js` as this will cause the browser to load the entire library. Instead, cherry pick from specific modules as shown above.