feat: add Shiki transformers for better syntax highlighting (satnaing#534)

* refactor: organize prose related styles inside nested prose

* feat: add Shiki transformers for better syntax highlighting

* chore: update blog posts using Shiki transformers

Closes satnaing#210

Author: satnaing

astro.config.ts

@@ -4,6 +4,11 @@ import sitemap from "@astrojs/sitemap";
 import remarkToc from "remark-toc";
 import remarkCollapse from "remark-collapse";
 import { SITE } from "./src/config";
+import {
+  transformerNotationDiff,
+  transformerNotationHighlight,
+  transformerNotationWordHighlight,
+} from "@shikijs/transformers";
 
 // https://astro.build/config
 export default defineConfig({
@@ -18,7 +23,13 @@ export default defineConfig({
     shikiConfig: {
       // For more themes, visit https://shiki.style/themes
       themes: { light: "min-light", dark: "night-owl" },
-      wrap: true,
+      defaultColor: false,
+      wrap: false,
+      transformers: [
+        transformerNotationDiff({ matchAlgorithm: "v3" }),
+        transformerNotationHighlight(),
+        transformerNotationWordHighlight(),
+      ],
     },
   },
   vite: {

package.json

@@ -29,6 +29,7 @@
   "devDependencies": {
     "@astrojs/check": "^0.9.4",
     "@pagefind/default-ui": "^1.3.0",
+    "@shikijs/transformers": "^3.6.0",
     "@tailwindcss/typography": "^0.5.16",
     "@types/lodash.kebabcase": "^4.1.9",
     "@typescript-eslint/parser": "^8.34.0",

pnpm-lock.yaml

@@ -44,8 +44,8 @@ If you don’t want subdirectories to affect the post URL, just prefix the folde
 src/data/blog/very-first-post.md          -> mysite.com/posts/very-first-post
 src/data/blog/2025/example-post.md        -> mysite.com/posts/2025/example-post
 src/data/blog/_2026/another-post.md       -> mysite.com/posts/another-post
-src/data/blog/docs/_legacy/how-to.md      -> mysite.com/docs/how-to
-src/data/blog/Example Dir/Dummy Post.md   -> mysite.com/example-dir/dummy-post
+src/data/blog/docs/_legacy/how-to.md      -> mysite.com/posts/docs/how-to
+src/data/blog/Example Dir/Dummy Post.md   -> mysite.com/posts/example-dir/dummy-post
 ```
 
 > 💡 Tip: You can override a blog post’s slug in the frontmatter as well. See the next section for more details.
@@ -91,6 +91,7 @@ If you omit `tags` in a blog post (in other words, if no tag is specified), the
 export const blogSchema = z.object({
   // ---
   draft: z.boolean().optional(),
+  // [!code highlight:1]
   tags: z.array(z.string()).default(["others"]), // replace "others" with whatever you want
   // ---
 });
@@ -128,17 +129,20 @@ Write `Table of contents` in h2 format (## in markdown) and place it where you w
 
 For instance, if you want to place your table of contents just under the intro paragraph (like I usually do), you can do that in the following way.
 
+<!-- prettier-ignore-start -->
 ```md
 ---
 # some frontmatter
 ---
 
 Here are some recommendations, tips & ticks for creating new posts in AstroPaper blog theme.
 
+<!-- [!code ++] -->
 ## Table of contents
 
 <!-- the rest of the post -->
 ```
+<!-- prettier-ignore-end -->
 
 ## Headings
 

src/data/blog/adding-new-post.md

@@ -43,15 +43,15 @@ In this section, you will find instructions on how to add support for LaTeX in y
      // other configs
      markdown: {
        remarkPlugins: [
-         remarkMath, // <- new plugin
+         remarkMath, // [!code ++]
          remarkToc,
          [remarkCollapse, { test: "Table of contents" }],
        ],
-       rehypePlugins: [rehypeKatex], // <- new plugin
+       rehypePlugins: [rehypeKatex], // [!code ++]
        shikiConfig: {
          // For more themes, visit https://shiki.style/themes
          themes: { light: "min-light", dark: "night-owl" },
-         wrap: true,
+         wrap: false,
        },
      },
      // other configs
@@ -71,6 +71,7 @@ In this section, you will find instructions on how to add support for LaTeX in y
    <!-- others... -->
    <script is:inline src="/toggle-theme.js"></script>
 
+   <!-- [!code highlight:4] -->
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css"
@@ -90,6 +91,7 @@ In this section, you will find instructions on how to add support for LaTeX in y
      /* other classes */
 
      /* Katex text color */
+     /* [!code highlight:3] */
      .prose .katex-display {
        @apply text-foreground;
      }

src/data/blog/how-to-add-latex-equations-in-blog-posts.md

@@ -77,18 +77,18 @@ You should now have a script tag that looks like this:
 
 Simply add that to the source code of the site. Most likely, if you're using _AstroPaper_ and want to enable comments on posts, navigate to `src/layouts/PostDetails.astro` and paste it into the desired location where you want the comments to appear, perhaps underneath the `Share this post on:` buttons.
 
-```diff
-      <ShareLinks />
-    </div>
-
-+    <script src="https://giscus.app/client.js"
-+        data-repo="[ENTER REPO HERE]"
-+        data-repo-id="[ENTER REPO ID HERE]"
-+        data-category="[ENTER CATEGORY NAME HERE]"
-+        data-category-id="[ENTER CATEGORY ID HERE]"
-+        ...
-+    </script>
-
+```astro
+<Layout {...layoutProps}>
+  <main>
+    <ShareLinks />
+
+    <!-- [!code ++:6] -->
+    <script
+      src="https://giscus.app/client.js"
+      data-repo="[ENTER REPO HERE]"
+      data-repo-id="[ENTER REPO ID HERE]"
+      data-category="[ENTER CATEGORY NAME HERE]"
+      data-category-id="[ENTER CATEGORY ID HERE]"></script>
   </main>
   <Footer />
 </Layout>
@@ -189,19 +189,18 @@ Note that specifying a `theme` here will override the `lightTheme` and `darkThem
 
 To complete the process, add the new Comments component to `src/layouts/PostDetails.astro` (replacing the `script` tag from the previous step).
 
-```diff
-+ import Comments from "@/components/Comments";
+```jsx
+// [!code ++:1]
+import Comments from "@/components/Comments";
 
-      <ShareLinks />
-    </div>
+<ShareLinks />
 
-+   <Comments client:only="react" />
+// [!code ++:1]
+<Comments client:only="react" />
 
-    <hr class="my-6 border-dashed" />
+<hr class="my-6 border-dashed" />
 
-  </main>
-  <Footer />
-</Layout>
+<Footer />
 ```
 
 And that's it!

src/data/blog/how-to-integrate-giscus-comments.md

@@ -142,15 +142,15 @@ To allow Astro to compile the markdown and do its thing, it needs to know what i
 
 To allow the key to be there with no value we need to edit line 10 to add the `.nullable()` function.
 
-```typescript
+```ts
 const blog = defineCollection({
   type: "content",
   schema: ({ image }) =>
     z.object({
       author: z.string().default(SITE.author),
       pubDatetime: z.date(),
--     modDatetime: z.date().optional(),
-+     modDatetime: z.date().optional().nullable(),
+      modDatetime: z.date().optional(), // [!code --]
+      modDatetime: z.date().optional().nullable(), // [!code ++]
       title: z.string(),
       featured: z.boolean().optional(),
       draft: z.boolean().optional(),
@@ -167,25 +167,23 @@ To stop the IDE complaining in the blog engine files I have also done the follow
 
 1. added `| null` to line 15 in `src/layouts/Layout.astro` so that it looks like
 
-```typescript
-export interface Props {
-  title?: string;
-  author?: string;
-  description?: string;
-  ogImage?: string;
-  canonicalURL?: string;
-  pubDatetime?: Date;
-  modDatetime?: Date | null;
-}
-```
-
-<!-- This needs to be 2 as it doesn't pick it up with the code block -->
+   ```typescript
+   export interface Props {
+     title?: string;
+     author?: string;
+     description?: string;
+     ogImage?: string;
+     canonicalURL?: string;
+     pubDatetime?: Date;
+     modDatetime?: Date | null;
+   }
+   ```
 
 2. added `| null` to line 5 in `src/components/Datetime.tsx` so that it looks like
 
-```typescript
-interface DatetimesProps {
-  pubDatetime: string | Date;
-  modDatetime: string | Date | undefined | null;
-}
-```
+   ```typescript
+   interface DatetimesProps {
+     pubDatetime: string | Date;
+     modDatetime: string | Date | undefined | null;
+   }
+   ```

src/data/blog/setting-dates-via-git-hooks.md

@@ -103,7 +103,10 @@ const nextPost =
       <Datetime {pubDatetime} {modDatetime} {timezone} size="lg" class="my-2" />
       <EditPost class="max-sm:hidden" {hideEditPost} {post} />
     </div>
-    <article id="article" class="mx-auto prose mt-8 max-w-app">
+    <article
+      id="article"
+      class="mx-auto prose mt-8 max-w-app prose-pre:bg-(--shiki-light-bg) dark:prose-pre:bg-(--shiki-dark-bg)"
+    >
       <Content />
     </article>
 

src/layouts/PostDetails.astro

@@ -1,35 +1,56 @@
 @plugin '@tailwindcss/typography';
 
 @layer base {
+  /* ===== Override default Tailwind Typography styles ===== */
   .prose {
     @apply prose-headings:!mb-3 prose-headings:!text-foreground prose-h3:italic prose-p:!text-foreground prose-a:!text-foreground prose-a:!decoration-dashed prose-a:underline-offset-8 hover:prose-a:text-accent prose-blockquote:!border-l-accent/50 prose-blockquote:opacity-80 prose-figcaption:!text-foreground prose-figcaption:opacity-70 prose-strong:!text-foreground prose-code:rounded prose-code:bg-muted/75 prose-code:p-1 prose-code:!text-foreground prose-code:before:!content-none prose-code:after:!content-none prose-ol:!text-foreground prose-ul:overflow-x-clip prose-ul:!text-foreground prose-li:marker:!text-accent prose-table:text-foreground prose-th:border prose-th:border-border prose-td:border prose-td:border-border prose-img:mx-auto prose-img:!my-2 prose-img:border-2 prose-img:border-border prose-hr:!border-border;
+
+    a {
+      @apply break-words hover:!text-accent;
+    }
+
+    details {
+      @apply inline-block cursor-pointer text-foreground select-none [&_p]:hidden [&_ul]:!my-0;
+    }
+
+    summary {
+      @apply focus-visible:no-underline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-accent focus-visible:outline-dashed;
+    }
+
+    thead th:first-child,
+    tbody td:first-child,
+    tfoot td:first-child {
+      padding-inline-start: 0.5714286em !important;
+    }
   }
-  .prose a {
-    @apply break-words hover:!text-accent;
-  }
-  .prose thead th:first-child,
-  tbody td:first-child,
-  tfoot td:first-child {
-    padding-inline-start: 0.5714286em !important;
-  }
-  .prose h2#table-of-contents {
-    @apply mb-2;
-  }
-  .prose details {
-    @apply inline-block cursor-pointer text-foreground select-none;
-  }
-  .prose summary {
-    @apply focus-visible:no-underline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-accent focus-visible:outline-dashed;
+
+  /* ===== Code Blocks & Syntax Highlighting ===== */
+  .astro-code {
+    @apply border bg-(--shiki-light-bg) text-(--shiki-light) outline-border [&_span]:text-(--shiki-light);
   }
-  .prose h2#table-of-contents + p {
-    @apply hidden;
+
+  html[data-theme="dark"] .astro-code {
+    @apply bg-(--shiki-dark-bg) text-(--shiki-dark) [&_span]:text-(--shiki-dark);
   }
 
-  /* ===== Code Blocks & Syntax Highlighting ===== */
-  pre:has(code) {
-    @apply border border-border;
+  /* Styles for Shiki transformers */
+  /* https://shiki.style/packages/transformers */
+  .astro-code {
+    .line.diff.add {
+      @apply relative *:bg-green-500/20 before:absolute before:-left-3 before:text-green-500 before:content-['+'];
+    }
+    .line.diff.remove {
+      @apply relative *:bg-red-500/30 before:absolute before:-left-3 before:text-red-500 before:content-['-'];
+    }
+    .line.highlighted {
+      @apply *:!bg-slate-400/20;
+    }
+    .highlighted-word {
+      @apply rounded-sm border border-border px-0.5 py-px;
+    }
   }
 
+  /* Break words in code and blockqoute */
   .prose code,
   .prose blockquote {
     @apply break-words;
@@ -39,18 +60,4 @@
     /* add line breaks whenever necessary for codes under table */
     @apply break-all sm:break-normal;
   }
-
-  pre > code {
-    white-space: pre;
-  }
-
-  /* Apply Dark Theme (if multi-theme specified) */
-  html[data-theme="dark"] pre:has(code),
-  html[data-theme="dark"] pre:has(code) span {
-    color: var(--shiki-dark) !important;
-    background-color: var(--shiki-dark-bg) !important;
-    font-style: var(--shiki-dark-font-style) !important;
-    font-weight: var(--shiki-dark-font-weight) !important;
-    text-decoration: var(--shiki-dark-text-decoration) !important;
-  }
 }