diff --git a/site/package-lock.json b/site/package-lock.json
index b44601837..3af28d0f1 100644
--- a/site/package-lock.json
+++ b/site/package-lock.json
@@ -10,6 +10,7 @@
       "devDependencies": {
         "@fontsource-variable/geist": "^5.2.8",
         "@shikijs/rehype": "^3.13.0",
+        "@shikijs/transformers": "^3.13.0",
         "@sveltejs/adapter-static": "^3.0.10",
         "@sveltejs/kit": "^2.43.2",
         "@sveltejs/vite-plugin-svelte": "^6.2.0",
@@ -977,6 +978,17 @@
         "@shikijs/types": "3.13.0"
       }
     },
+    "node_modules/@shikijs/transformers": {
+      "version": "3.13.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/transformers/-/transformers-3.13.0.tgz",
+      "integrity": "sha512-833lcuVzcRiG+fXvgslWsM2f4gHpjEgui1ipIknSizRuTgMkNZupiXE5/TVJ6eSYfhNBFhBZKkReKWO2GgYmqA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/core": "3.13.0",
+        "@shikijs/types": "3.13.0"
+      }
+    },
     "node_modules/@shikijs/types": {
       "version": "3.13.0",
       "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-3.13.0.tgz",
diff --git a/site/package.json b/site/package.json
index 6b706e6ff..701408457 100644
--- a/site/package.json
+++ b/site/package.json
@@ -16,6 +16,7 @@
   "devDependencies": {
     "@fontsource-variable/geist": "^5.2.8",
     "@shikijs/rehype": "^3.13.0",
+    "@shikijs/transformers": "^3.13.0",
     "@sveltejs/adapter-static": "^3.0.10",
     "@sveltejs/kit": "^2.43.2",
     "@sveltejs/vite-plugin-svelte": "^6.2.0",
diff --git a/site/src/routes/docs/[...path]/+page.svelte b/site/src/routes/docs/[...path]/+page.svelte
index 4a37019ac..91efb35d7 100644
--- a/site/src/routes/docs/[...path]/+page.svelte
+++ b/site/src/routes/docs/[...path]/+page.svelte
@@ -10,11 +10,21 @@
 
 <style>
 :global {
+
+.shiki code {
+  display: block;
+}
+.shiki .line {
+  width: 100%;
+  display: inline-block;
+}
+
+/* line number */
 .shiki code {
   counter-reset: step;
   counter-increment: step 0;
 }
-.line::before {
+.shiki .line::before {
   content: counter(step);
   counter-increment: step;
   width: 1rem;
@@ -23,5 +33,38 @@
   text-align: right;
   color: rgba(115,138,148,.4);
 }
+
+/* indent guides */
+.shiki .indent {
+  display: inline-block;
+  position: relative;
+  left: var(--indent-offset);
+}
+
+.shiki .indent:empty {
+  height: 1lh;
+  vertical-align: bottom;
+}
+
+.shiki .indent::before {
+  content: '';
+  position: absolute;
+  opacity: 0.15;
+  width: 1px;
+  height: 100%;
+  background-color: currentColor;
+}
+
+
+/* diff */
+.shiki .line.diff.remove {
+  background-color: #db0a0a41;
+}
+.shiki .line.diff.add {
+  background-color: #0adb4954;
+}
+.shiki .line.highlighted {
+  background-color: #00000024;
+}
 }
 </style>
diff --git a/site/src/routes/docs/[...path]/+page.ts b/site/src/routes/docs/[...path]/+page.ts
index 5a077734e..9e1c8a2c3 100644
--- a/site/src/routes/docs/[...path]/+page.ts
+++ b/site/src/routes/docs/[...path]/+page.ts
@@ -1,5 +1,4 @@
 import { error } from "@sveltejs/kit";
-import type { Component } from "svelte";
 
 const articles = import.meta.glob<{
   default: string;
diff --git a/site/src/routes/docs/getting-started/overview.md b/site/src/routes/docs/getting-started/overview.md
index 84f9e3b81..81acea225 100644
--- a/site/src/routes/docs/getting-started/overview.md
+++ b/site/src/routes/docs/getting-started/overview.md
@@ -16,4 +16,34 @@ const abc = 1 + "2";
 
 ## Step Bar
 
+```nix {1,18-21}
+inventory.instances = {
+  dyndns = {
+    roles.default.machines."jon" = { }; # [!code --]
+    roles.default.settings = { # [!code ++]
+      period   = 15;                # minutes
+      settings = {
+        "all-jon-blog" = {
+          provider         = "porkbun";
+          domain           = "jon.blog";
+
+          # (1) tell the secret-manager which key we are going to store
+          secret_field_name = "secret_api_key";
+
+          # everything below is copied verbatim into config.json
+          extraSettings = {
+            host         = "@,home,test";   # (2) comma-separated list of sub-domains [!code highlight]
+            ip_version   = "ipv4";
+            ipv6_suffix  = "";
+            api_key      = "pk1_4bb2b231275a02fdc23b7e6f3552s01S213S"; # (3) public – safe to commit
+          };
+        };
+      };
+    };
+  };
+};
+```
+
+## Step Foo
+
 ## Step Bar
diff --git a/site/src/routes/index.css b/site/src/routes/index.css
index 8c009d907..a996e538d 100644
--- a/site/src/routes/index.css
+++ b/site/src/routes/index.css
@@ -2,4 +2,4 @@
 
 body {
   font-family: "Geist Variable";
-}
\ No newline at end of file
+}
diff --git a/site/vite.config.ts b/site/vite.config.ts
index 918b653f2..1095e7948 100644
--- a/site/vite.config.ts
+++ b/site/vite.config.ts
@@ -11,6 +11,12 @@ import rehypeSlug from "rehype-slug";
 import rehypeAutolinkHeadings from "rehype-autolink-headings";
 import { toc } from "mdast-util-toc";
 import type { Nodes } from "mdast";
+import {
+  transformerNotationDiff,
+  transformerNotationHighlight,
+  transformerRenderIndentGuides,
+  transformerMetaHighlight,
+} from "@shikijs/transformers";
 
 export default defineConfig({
   plugins: [
@@ -31,6 +37,14 @@ export default defineConfig({
               light: "vitesse-light",
               dark: "vitesse-dark",
             },
+            transformers: [
+              transformerNotationDiff({
+                matchAlgorithm: "v3",
+              }),
+              transformerNotationHighlight(),
+              transformerRenderIndentGuides(),
+              transformerMetaHighlight(),
+            ],
           })
           .use(rehypeStringify)
           .use(rehypeSlug)