diff --git a/.changeset/thirty-ways-kick.md b/.changeset/thirty-ways-kick.md
new file mode 100644
index 0000000..1d7c127
--- /dev/null
+++ b/.changeset/thirty-ways-kick.md
@@ -0,0 +1,10 @@
+---
+'svelte-pp-markdown': patch
+'svelte-pp-katex': patch
+'svelte-pp-shiki': patch
+'@samplekit/preprocess-markdown': patch
+'@samplekit/preprocess-katex': patch
+'@samplekit/preprocess-shiki': patch
+---
+
+update readme
diff --git a/packages/preprocess-katex-vscode/README.md b/packages/preprocess-katex-vscode/README.md
index 93c306f..7663e86 100644
--- a/packages/preprocess-katex-vscode/README.md
+++ b/packages/preprocess-katex-vscode/README.md
@@ -1,41 +1,43 @@
-# KaTeX TextMate Grammar Injection into Svelte Templates
+# Syntax Highlighting for Math in Svelte Templates
-Accompanies the @samplekit/preprocess-katex npm package to inject syntax highlighting into the Svelte template math blocks.
+This extension adds syntax highlighting to – and snippets for – the [@samplekit/preprocess-katex](https://www.npmjs.com/package/@samplekit/preprocess-katex) NPM package.
-## Features
+The NPM package allows you to write math (via KaTeX) directly in Svelte templates without disrupting other tools like svelte-check, Prettier, ESLint, TypeScript, etc.
-- injects [text.tex.latex meta.math.block.latex support.class.math.block.environment.latex]() highlighting into HTML comments inside Svelte markup.
-- injects [text.katex scope](https://github.com/yzhang-gh/vscode-markdown/blob/master/syntaxes/katex.tmLanguage.json) into tagged template literals in JS
-- adds snippets to make it quicker to generate the required HTML comments.
+## Examples
-## Svelte HTML Comments
+### In Svelte Markup
-By using HTML comments, it's trivial to write a preprocessor without running afoul of svelte check, prettier, eslint, typescript, etc.
-
-#### `` (KaTeX display mode) and `` (KaTeX inline mode)
-
-Before
+#### Without Extension
-After
+#### With Extension
-## JS/TS Template Literals
-
-A tagged template literal is used to inject KaTeX highlighting into JS.
-
-#### katex\`
or latex\`
(case insensitive)
+### In JS Tagged Template Literal
-Before
+#### Without Extension
-After
+#### With Extension
-## Extension
+## Supported Syntax
+
+The supported syntax matches that of the NPM package's preprocessor.
+
+In Svelte markup, use `` for display mode and `` for inline mode.
+
+For JS tagged template literals, use katex\`
or latex\`
(case insensitive).
+
+## Links
-> [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-katex)
+- [Docs](https://preprocessors.samplekit.dev/docs/math/)
+- [Extension on the VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-katex)
+- [Extension Source](https://github.com/timothycohen/samplekit/tree/main/packages/preprocess-katex-vscode)
+- [Companion NPM Package](https://www.npmjs.com/package/@samplekit/preprocess-katex)
+- [Companion Package Source](https://github.com/timothycohen/samplekit/tree/main/packages/preprocess-katex)
diff --git a/packages/preprocess-katex/readme.md b/packages/preprocess-katex/readme.md
index a569e62..a1e47c8 100644
--- a/packages/preprocess-katex/readme.md
+++ b/packages/preprocess-katex/readme.md
@@ -4,14 +4,18 @@
## What is `preprocess-katex`?
-`preprocess-katex` is a preprocessor for Svelte which allows you to write KaTeX directly in Svelte templates.
+`preprocess-katex` is a preprocessor for Svelte which allows you to write math (via KaTeX) directly in Svelte templates without disrupting other tools like svelte-check, Prettier, ESLint, TypeScript, etc.
-It uses HTML comments so you don't have to worry about conflicts with your other tooling.
-
-The [NPM package](https://www.npmjs.com/package/@samplekit/preprocess-katex) has a corresponding [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-katex) to provide semantic highlighting.
+This package has a corresponding [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-katex) to provide syntax highlighting.
## Member of the [@samplekit](https://github.com/timothycohen/samplekit) Preprocessor Family.
-[Docs available here](https://preprocessors.samplekit.dev/docs/math/).
-
+
+## Links
+
+- [Docs](https://preprocessors.samplekit.dev/docs/math/)
+- [NPM Package](https://www.npmjs.com/package/@samplekit/preprocess-katex)
+- [NPM Package Source](https://github.com/timothycohen/samplekit/tree/main/packages/preprocess-katex)
+- [Companion VSCode Extension](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-katex)
+- [Companion Extension Source](https://github.com/timothycohen/samplekit/tree/main/packages/preprocess-katex-vscode)
diff --git a/packages/preprocess-markdown-vscode/README.md b/packages/preprocess-markdown-vscode/README.md
index 6928325..26db796 100644
--- a/packages/preprocess-markdown-vscode/README.md
+++ b/packages/preprocess-markdown-vscode/README.md
@@ -1,26 +1,29 @@
-# Markdown TextMate Grammar Injection into Svelte Templates
+# Syntax Highlighting for Markdown in Svelte Templates
-Accompanies the @samplekit/preprocess-katex npm package to inject syntax highlighting into the Svelte template markdown blocks.
+This extension adds syntax highlighting to – and snippets for – the [@samplekit/preprocess-markdown](https://www.npmjs.com/package/@samplekit/preprocess-markdown) NPM package.
-## Features
+The NPM package allows you to write Markdown (via Marked) directly in Svelte templates without disrupting other tools like svelte-check, Prettier, ESLint, TypeScript, etc.
-- injects Markdown highlighting into HTML comments inside Svelte markup.
-- adds snippets to make it quicker to generate the required HTML comments.
+## Examples
-## Svelte HTML Comments
+### Without Extension
-By using HTML comments, it's trivial to write a preprocessor without running afoul of svelte check, prettier, eslint, typescript, etc.
+
-#### ``
+### With Extension
-Before
+
-
+## Supported Syntax
-After
+The supported syntax matches that of the NPM package's preprocessor.
-
+In Svelte markup, wrap Markdown with ``.
-## Extension
+## Links
-> [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-markdown)
+- [Docs](https://preprocessors.samplekit.dev/docs/markdown/)
+- [Extension on the VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-markdown)
+- [Extension Source](https://github.com/timothycohen/samplekit/tree/main/packages/preprocess-markdown-vscode)
+- [Companion NPM Package](https://www.npmjs.com/package/@samplekit/preprocess-markdown)
+- [Companion Package Source](https://github.com/timothycohen/samplekit/tree/main/packages/preprocess-markdown)
diff --git a/packages/preprocess-markdown/readme.md b/packages/preprocess-markdown/readme.md
index 73c8cb6..00b653c 100644
--- a/packages/preprocess-markdown/readme.md
+++ b/packages/preprocess-markdown/readme.md
@@ -4,14 +4,18 @@
## What is `preprocess-markdown`?
-`preprocess-markdown` is a preprocessor for Svelte which allows you to write Markdown directly in Svelte templates.
+`preprocess-markdown` is a preprocessor for Svelte which allows you to write Markdown (via Marked) directly in Svelte templates without disrupting other tools like svelte-check, Prettier, ESLint, TypeScript, etc.
-It uses HTML comments so you don't have to worry about conflicts with your other tooling.
-
-The [NPM package](https://www.npmjs.com/package/@samplekit/preprocess-markdown) has a corresponding [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-markdown) to provide semantic highlighting.
+This package has a corresponding [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-markdown) to provide syntax highlighting.
## Member of the [@samplekit](https://github.com/timothycohen/samplekit) Preprocessor Family.
-[Docs available here](https://preprocessors.samplekit.dev/docs/markdown/).
-
+
+## Links
+
+- [Docs](https://preprocessors.samplekit.dev/docs/markdown/)
+- [NPM Package](https://www.npmjs.com/package/@samplekit/preprocess-markdown)
+- [NPM Package Source](https://github.com/timothycohen/samplekit/tree/main/packages/preprocess-markdown)
+- [Companion VSCode Extension](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-markdown)
+- [Companion Extension Source](https://github.com/timothycohen/samplekit/tree/main/packages/preprocess-markdown-vscode)
diff --git a/packages/preprocess-shiki-vscode/README.md b/packages/preprocess-shiki-vscode/README.md
index 44a1b32..227a5b8 100644
--- a/packages/preprocess-shiki-vscode/README.md
+++ b/packages/preprocess-shiki-vscode/README.md
@@ -1,26 +1,29 @@
-# Codeblock TextMate Grammar Injection into Svelte Templates
+# Syntax Highlighting for Decorated Code Blocks in Svelte Templates
-Accompanies the @samplekit/preprocess-shiki npm package to inject syntax highlighting into the Svelte template code blocks.
+This extension adds syntax highlighting to – and snippets for – the [@samplekit/preprocess-shiki](https://www.npmjs.com/package/@samplekit/preprocess-shiki) NPM package.
-## Features
+The NPM package allows you to write decorated code blocks (via Shiki) directly in Svelte templates without disrupting other tools like svelte-check, Prettier, ESLint, TypeScript, etc.
-- injects code highlighting into HTML comments inside Svelte markup.
-- adds snippets to make it quicker to generate the required HTML comments.
+## Examples
-## Svelte HTML Comments
+### Without Extension
-By using HTML comments, it's trivial to write a preprocessor without running afoul of svelte check, prettier, eslint, typescript, etc.
+
-#### ``
+### With Extension
-Before
+
-
+## Supported Syntax
-After
+The supported syntax matches that of the NPM package's preprocessor.
-
+In Svelte markup, wrap blocks with `` and one liners with ``, ``, etc.
-## Extension
+## Links
-> [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-shiki)
+- [Docs](https://preprocessors.samplekit.dev/docs/code-decoration/)
+- [Extension on the VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-shiki)
+- [Extension Source](https://github.com/timothycohen/samplekit/tree/main/packages/preprocess-shiki-vscode)
+- [Companion NPM Package](https://www.npmjs.com/package/@samplekit/preprocess-shiki)
+- [Companion Package Source](https://github.com/timothycohen/samplekit/tree/main/packages/preprocess-shiki)
diff --git a/packages/preprocess-shiki/readme.md b/packages/preprocess-shiki/readme.md
index 9187f1e..d395f2b 100644
--- a/packages/preprocess-shiki/readme.md
+++ b/packages/preprocess-shiki/readme.md
@@ -4,14 +4,18 @@
## What is `preprocess-shiki`?
-`preprocess-shiki` is a preprocessor for Svelte which allows you to write Shiki code blocks directly in Svelte templates.
+`preprocess-shiki` is a preprocessor for Svelte which allows you to write decorated code blocks (via Shiki) directly in Svelte templates without disrupting other tools like svelte-check, Prettier, ESLint, TypeScript, etc.
-It uses HTML comments so you don't have to worry about conflicts with your other tooling.
-
-The [NPM package](https://www.npmjs.com/package/@samplekit/preprocess-shiki) has a corresponding [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-shiki) to provide semantic highlighting.
+This package has a corresponding [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-shiki) to provide syntax highlighting.
## Member of the [@samplekit](https://github.com/timothycohen/samplekit) Preprocessor Family.
-[Docs available here](https://preprocessors.samplekit.dev/docs/code-decoration/).
-
+
+## Links
+
+- [Docs](https://preprocessors.samplekit.dev/docs/code-decoration/)
+- [NPM Package](https://www.npmjs.com/package/@samplekit/preprocess-shiki)
+- [NPM Package Source](https://github.com/timothycohen/samplekit/tree/main/packages/preprocess-shiki)
+- [Companion VSCode Extension](https://marketplace.visualstudio.com/items?itemName=samplekit.svelte-pp-shiki)
+- [Companion Extension Source](https://github.com/timothycohen/samplekit/tree/main/packages/preprocess-shiki-vscode)