From fd7cf716f52954d3f25455fd88e9c8cd66197f78 Mon Sep 17 00:00:00 2001
From: cfngc4594 <cfngc4594@gmail.com>
Date: Sun, 2 Mar 2025 11:39:08 +0800
Subject: [PATCH] docs(readme): improve README with detailed WSL setup and
 package compatibility info

---
 README.md | 63 ++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 39 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index c889d7f..abfdd4a 100644
--- a/README.md
+++ b/README.md
@@ -2,56 +2,53 @@
 
 # monaco-editor-lsp-next
 
-✨ A Next.js integration of Monaco Editor with LSP support, free from SSR issues.
+✨ A seamless Next.js integration of the Monaco Editor with robust LSP support – all without SSR hassles.
 
 ![demo](demo.png)
 
 </div>
 
-## ⚠️ Important Notice for WSL Users!
+## ⚠️ Important Notice for WSL Users
 
-If you're using Windows Subsystem for Linux (WSL), it's **crucial** to switch your network mode to "Mirrored".
+### 🐧 WSL Network Configuration
 
-Otherwise, the Monaco Editor might fail to connect to the LSP language servers.
+If you are using Windows Subsystem for Linux (WSL), it is **essential** to switch your network mode to **Mirrored**. Failing to do so may prevent the Monaco Editor from connecting to the LSP language servers due to potential IPv6 configuration conflicts.
 
-This is typically due to IPv6 configuration issues.
+#### Steps to Switch to "Mirrored" Mode:
+1. Open your WSL settings. ⚙️  
+2. Navigate to the **Network** section. 🌐  
+3. Change the network mode to **Mirrored**. 🔄  
+4. Restart WSL. 💻  
 
-To change your WSL network mode, follow these steps:
+Once these steps are completed, the Monaco Editor should connect smoothly to the LSP language servers. Enjoy! 🎉
 
-1. Open WSL settings. ⚙️
-2. Navigate to the "Network" section. 🌐
-3. Change the network mode to "Mirrored". 🔄
-4. Restart WSL. 💻
-
-After completing these steps, the Monaco Editor should be able to connect to the LSP language servers without any problems. 🎉
-
-## 🚀 Quick Start
+## 🚀 Quick Start Guide
 
 ### 🐳 Using Docker (Recommended)
 
 ```sh
-# Clone repository
+# Clone the repository
 git clone https://github.com/cfngc4594/monaco-editor-lsp-next
 cd monaco-editor-lsp-next
 
-# Start containers in detached mode
+# Build and start containers in detached mode
 docker compose up -d --build
 ```
 
 ### 🔧 Manual Setup
 
 ```sh
-# Clone repository
+# Clone the repository
 git clone https://github.com/cfngc4594/monaco-editor-lsp-next
 cd monaco-editor-lsp-next
 
-# Start specific containers (lsp-c and lsp-cpp) in detached mode
+# Build and start specific containers (lsp-c and lsp-cpp) in detached mode
 docker compose up -d --build lsp-c lsp-cpp
 
-# Install project dependencies using Bun package manager
+# Install project dependencies using the Bun package manager
 bun install
 
-# Run the development server
+# Launch the development server
 bun run dev
 ```
 
@@ -59,7 +56,25 @@ bun run dev
 
 ### LSP Server Settings
 
-|  **Language**  |  **LSP Server**  |  **Port**  |
-|----------------|------------------|------------|
-| `C`            | `clangd`         | `4594`     |
-| `C++`          | `clangd`         | `4595`     |
+| **Language** | **LSP Server** | **Port** |
+|--------------|----------------|----------|
+| `C`          | `clangd`       | `4594`   |
+| `C++`        | `clangd`       | `4595`   |
+
+## 📦 Package Compatibility
+
+### 🎨 Shiki API Deprecation Notice
+
+The syntax highlighting feature relies on `rehype-pretty-code`, which uses the deprecated `getHighlighter` API from `shiki`. This API was removed as of `shiki@3.0.0+`.
+
+**Key Details:**
+- **Affected Component:** `src/components/mdx-preview.tsx`
+- **Dependency Chain:** `rehype-pretty-code` → `shiki@legacy`
+- **Version Constraints:**
+  ```bash
+  "shiki": "<=2.5.0"
+  "@shikijs/monaco": "<=2.5.0"
+  ```
+
+**Developer Note:**  
+Although newer shiki versions (3.0.0+) have introduced `createHighlighter` and `getSingletonHighlighter` APIs, upgrading manually may disrupt functionality until `rehype-pretty-code` adapts to these changes. For updates, please monitor the [rehype-pretty-code repository](https://github.com/atomiks/rehype-pretty-code).