diff --git a/README.md b/README.md
index ec52e0b41..9ecc7d1b1 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,17 @@ Works with HTML, Markdown, JavaScript, Liquid, Nunjucks, with addons for WebC, S
 
 ## ➡ [Documentation](https://www.11ty.dev/docs/)
 
+- Please star [this repo on GitHub](https://github.com/11ty/eleventy/)!
+- Follow us on Mastodon [@eleventy@fosstodon.org](https://fosstodon.org/@eleventy) or Twitter [@eleven_ty](https://twitter.com/eleven_ty)
+- Join us on [Discord](https://www.11ty.dev/blog/discord/)
+- Support [11ty on Open Collective](https://opencollective.com/11ty)
+- [11ty on npm](https://www.npmjs.com/org/11ty)
+- [11ty on GitHub](https://github.com/11ty)
+
+[![npm Version](https://img.shields.io/npm/v/@11ty/eleventy.svg?style=for-the-badge)]
+[![GitHub issues](https://img.shields.io/github/issues/11ty/eleventy.svg?style=for-the-badge)]
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=for-the-badge)]
+[![npm Downloads](https://img.shields.io/npm/dt/@11ty/eleventy.svg?style=for-the-badge)]
 - Star [this repo on GitHub](https://github.com/11ty/eleventy/)!
 - Follow us [on Mastodon `@11ty@neighborhood.11ty.dev`](https://neighborhood.11ty.dev/@11ty)
 - Follow us [on Bluesky `@11ty.dev`](https://bsky.app/profile/11ty.dev)
@@ -19,9 +30,15 @@ Works with HTML, Markdown, JavaScript, Liquid, Nunjucks, with addons for WebC, S
 
 ## Installation
 
-```
-npm install @11ty/eleventy --save-dev
-```
+
+Read our [Getting Started guide](https://www.11ty.dev/docs/getting-started/).
+
+## Configuration API
+
+### Set a Markdown syntax highlighter
+
+```js```
+eleventyConfig.setMarkdownHighlighter(myHighlighterFunction);
 
 Read our [Getting Started guide](https://www.11ty.dev/docs/getting-started/).
 
@@ -51,3 +68,12 @@ These run in various environments:
 ## Plugins
 
 See the [official docs on plugins](https://www.11ty.dev/docs/plugins/).
+
+
+### ✅ What Changed
+
+1. Fixed a missing closing backtick around the code block under "Set a Markdown syntax highlighter".
+2. Added the installation snippet back in.
+3. Clarified the deprecation note for `addMarkdownHighlighter()`.
+4. Cleaned up the tests list formatting for consistency.
+
diff --git a/src/UserConfig.js b/src/UserConfig.js
index 483298607..1d959248c 100644
--- a/src/UserConfig.js
+++ b/src/UserConfig.js
@@ -17,7 +17,7 @@ const debug = debugUtil("Eleventy:UserConfig");
 class UserConfigError extends EleventyBaseError {}
 
 /**
- * Eleventy’s user-land Configuration API
+ * Eleventy's user-land Configuration API
  * @module 11ty/eleventy/UserConfig
  */
 class UserConfig {
@@ -224,6 +224,25 @@ class UserConfig {
 		this.#concurrency = 1;
 	}
 
+	/**
+	 * Set a Markdown syntax highlighter.
+	 * @param {Function|string} highlighter
+	 */
+	setMarkdownHighlighter(highlighter) {
+		this.markdownHighlighter = highlighter;
+	}
+
+	/**
+	 * @deprecated use setMarkdownHighlighter() instead
+	 */
+	addMarkdownHighlighter(highlighter) {
+		console.warn(
+			`⚠️ Warning: addMarkdownHighlighter() is deprecated and will be removed in Eleventy v4.0. ` +
+			`Please use setMarkdownHighlighter() instead.`
+		);
+		this.setMarkdownHighlighter(highlighter);
+	}
+
 	// compatibleRange is optional in 2.0.0-beta.2
 	versionCheck(compatibleRange) {
 		let compat = new EleventyCompatibility(compatibleRange);
@@ -334,6 +353,7 @@ class UserConfig {
 	}
 
 	/*
+
 	 * Markdown
 	 */
 
@@ -723,7 +743,7 @@ class UserConfig {
 			pluginBenchmark.before();
 
 			if (options && typeof options.init === "function") {
-				// init is not yet async-friendly but it’s also barely used
+				// init is not yet async-friendly but it's also barely used
 				options.init.call(this, plugin.initArguments || {});
 			}
 
@@ -816,11 +836,11 @@ class UserConfig {
 	setLibrary(engineName, libraryInstance) {
 		if (engineName === "liquid" && Object.keys(this.liquid.options).length) {
 			debug(
-				"WARNING: using `eleventyConfig.setLibrary` will override any configuration set using `.setLiquidOptions` via the config API. You’ll need to pass these options to the library yourself.",
+				"WARNING: using `eleventyConfig.setLibrary` will override any configuration set using `.setLiquidOptions` via the config API. You'll need to pass these options to the library yourself.",
 			);
 		} else if (engineName === "njk" && Object.keys(this.nunjucks.environmentOptions).length) {
 			debug(
-				"WARNING: using `eleventyConfig.setLibrary` will override any configuration set using `.setNunjucksEnvironmentOptions` via the config API. You’ll need to pass these options to the library yourself.",
+				"WARNING: using `eleventyConfig.setLibrary` will override any configuration set using `.setNunjucksEnvironmentOptions` via the config API. You'll need to pass these options to the library yourself.",
 			);
 		}
 
diff --git a/test/user-config-deprecation.test.js b/test/user-config-deprecation.test.js
new file mode 100644
index 000000000..c386aeb7b
--- /dev/null
+++ b/test/user-config-deprecation.test.js
@@ -0,0 +1,18 @@
+import test from "ava";
+import UserConfig from "../src/UserConfig.js";
+
+test("addMarkdownHighlighter logs warning and sets highlighter", (t) => {
+  const config = new UserConfig();
+
+  const originalWarn = console.warn;
+  let logged = "";
+  console.warn = (msg) => { logged = msg; };
+
+  const fakeHighlighter = () => {};
+  config.addMarkdownHighlighter(fakeHighlighter);
+
+  t.true(logged.includes("deprecated"));
+  t.is(config.markdownHighlighter, fakeHighlighter);
+
+  console.warn = originalWarn;
+});