From 54d62ff0806bec3f06ff3ccb1cf2de5b172f7f65 Mon Sep 17 00:00:00 2001
From: Ayo <ayo@ayco.io>
Date: Sat, 25 Jul 2026 09:37:02 +0200
Subject: [PATCH] docs: add `distPaths()` section to cem-plugin guide

---
 .gitignore                                  |  3 ++
 docs/src/content/docs/guides/cem-plugin.mdx | 41 ++++++++++-----------
 2 files changed, 23 insertions(+), 21 deletions(-)

diff --git a/.gitignore b/.gitignore
index 74cc564..1e4ac3e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,3 +25,6 @@ storybook/custom-elements.json
 # so `html.customData` in .vscode/settings.json can resolve it
 vscode.html-custom-data.json
 vscode.css-custom-data.json
+
+# `cem analyze` outputs using `wcb` plugins
+.wcb
\ No newline at end of file
diff --git a/docs/src/content/docs/guides/cem-plugin.mdx b/docs/src/content/docs/guides/cem-plugin.mdx
index b06707c..36a44ef 100644
--- a/docs/src/content/docs/guides/cem-plugin.mdx
+++ b/docs/src/content/docs/guides/cem-plugin.mdx
@@ -49,12 +49,25 @@ Then run the analyzer:
 npx cem analyze
 ```
 
-<Aside type="caution" title="Publishing a package? Point the manifest at your built files">
-  The analyzer stamps each module's `path` with the exact file it scanned —
-  so with `globs: ['src/**/*.ts']` every `path` in `custom-elements.json` is a
-  `.ts` source file. Most packages publish only their built `dist/` output
-  (and can't `import` a `.ts` at runtime anyway), so a consumer reading that
-  manifest resolves paths that aren't in the tarball.
+<Aside type="caution" title="LOOK OUT! `cem analyze` fails by hanging, not by erroring">
+  Run it **from the directory holding your config and a `package.json`**. Two
+  things make it appear to do nothing, neither of which prints an error:
+
+- **No config found**: it falls back to a default glob of
+  `**/*.{js,ts,tsx}`, which does _not_ exclude `node_modules`. In a real
+  project that is tens of thousands of files through the TypeScript parser.
+- **No `package.json` in the directory**: it hangs outright.
+
+With globs scoped to your source it should finish in well under a second.
+</Aside>
+
+### Prepare to publish a package with `distPaths()`
+
+The analyzer stamps each module's `path` with the exact file it scanned —
+so with `globs: ['src/**/*.ts']` every `path` in `custom-elements.json` is a
+`.ts` source file. Most packages publish only their built `dist/` output
+(and can't `import` a `.ts` at runtime anyway), so a consumer reading that
+manifest resolves paths that aren't in the tarball.
 
 Add `distPaths()` after `wcbStaticProps()` to rewrite those paths to the
 built output. Zero-config it maps `src/` → `dist/` and TypeScript extensions
@@ -70,26 +83,12 @@ export default {
 }
 ```
 
-For a different layout, override `rootDir` / `outDir` (named to mirror
-`tsconfig`): `distPaths({ rootDir: 'lib', outDir: 'dist/esm' })`. Run
+For a different layout, override `rootDir` / `outDir`: `distPaths({ rootDir: 'lib', outDir: 'dist/esm' })`. Run
 `cem analyze` **after** your build so the `dist/` files it points at exist.
 Not publishing the manifest — e.g. a local Storybook or editor setup over
 your own source — needs none of this.
 
-</Aside>
 
-<Aside type="caution" title="LOOK OUT! `cem analyze` fails by hanging, not by erroring">
-  Run it **from the directory holding your config and a `package.json`**. Two
-  things make it appear to do nothing, neither of which prints an error:
-
-- **No config found**: it falls back to a default glob of
-  `**/*.{js,ts,tsx}`, which does _not_ exclude `node_modules`. In a real
-  project that is tens of thousands of files through the TypeScript parser.
-- **No `package.json` in the directory**: it hangs outright.
-
-With globs scoped to your source it should finish in well under a second.
-
-</Aside>
 
 ## What it produces