diff --git a/app/pages/code/[...path].vue b/app/pages/code/[...path].vue
index 72dee493cf..13f72d70c5 100644
--- a/app/pages/code/[...path].vue
+++ b/app/pages/code/[...path].vue
@@ -243,6 +243,22 @@ const canonicalUrl = computed(() => {
   return url
 })
 
+// Toggle markdown view mode
+const markdownViewModes = [
+  {
+    key: 'preview',
+    label: $t('code.markdown_view_mode.preview'),
+    icon: 'i-carbon-view',
+  },
+  {
+    key: 'code',
+    label: $t('code.markdown_view_mode.code'),
+    icon: 'i-carbon-code',
+  },
+] as const
+
+const markdownViewMode = ref<(typeof markdownViewModes)[number]['key']>('preview')
+
 useHead({
   link: [{ rel: 'canonical', href: canonicalUrl }],
 })
@@ -359,15 +375,39 @@ useSeoMeta({
         <!-- File viewer -->
         <template v-if="isViewingFile && fileContent">
           <div
-            class="sticky top-0 bg-bg border-b border-border px-4 py-2 flex items-center justify-between"
+            class="sticky z-10 top-0 bg-bg border-b border-border px-4 py-2 flex items-center justify-between"
           >
-            <div class="flex items-center gap-3 text-sm">
-              <span class="text-fg-muted">{{
-                $t('code.lines', { count: fileContent.lines })
-              }}</span>
-              <span v-if="currentNode?.size" class="text-fg-subtle">{{
-                formatBytes(currentNode.size)
-              }}</span>
+            <div class="flex items-center gap-2">
+              <div
+                v-if="fileContent.markdownHtml"
+                class="flex items-center gap-1 p-0.5 bg-bg-subtle border border-border-subtle rounded-md overflow-x-auto"
+                role="tablist"
+                aria-label="Markdown view mode selector"
+              >
+                <button
+                  v-for="mode in markdownViewModes"
+                  :key="mode.key"
+                  role="tab"
+                  class="px-2 py-1.5 font-mono text-xs rounded transition-colors duration-150 border border-solid focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fg/50 inline-flex items-center gap-1.5"
+                  :class="
+                    markdownViewMode === mode.key
+                      ? 'bg-bg shadow text-fg border-border'
+                      : 'text-fg-subtle hover:text-fg border-transparent'
+                  "
+                  @click="markdownViewMode = mode.key"
+                >
+                  <span class="inline-block h-3 w-3" :class="mode.icon" aria-hidden="true" />
+                  {{ mode.label }}
+                </button>
+              </div>
+              <div class="flex items-center gap-3 text-sm">
+                <span class="text-fg-muted">{{
+                  $t('code.lines', { count: fileContent.lines })
+                }}</span>
+                <span v-if="currentNode?.size" class="text-fg-subtle">{{
+                  formatBytes(currentNode.size)
+                }}</span>
+              </div>
             </div>
             <div class="flex items-center gap-2">
               <button
@@ -389,7 +429,19 @@ useSeoMeta({
               </a>
             </div>
           </div>
+          <div
+            v-if="fileContent.markdownHtml"
+            v-show="markdownViewMode === 'preview'"
+            class="flex justify-center p-4"
+          >
+            <div
+              class="readme-content prose prose-invert max-w-[70ch]"
+              v-html="fileContent.markdownHtml.html"
+            ></div>
+          </div>
+
           <CodeViewer
+            v-show="!fileContent.markdownHtml || markdownViewMode === 'code'"
             :html="fileContent.html"
             :lines="fileContent.lines"
             :selected-lines="selectedLines"
diff --git a/i18n/locales/ar.json b/i18n/locales/ar.json
index ef1feec9de..c858a3cb18 100644
--- a/i18n/locales/ar.json
+++ b/i18n/locales/ar.json
@@ -532,6 +532,10 @@
     "table": {
       "name": "الاسم",
       "size": "الحجم"
+    },
+    "markdown_view_mode": {
+      "preview": "معاينة",
+      "code": "الكود"
     }
   },
   "badges": {
diff --git a/i18n/locales/de-DE.json b/i18n/locales/de-DE.json
index bf1390d3d2..72bd00da77 100644
--- a/i18n/locales/de-DE.json
+++ b/i18n/locales/de-DE.json
@@ -532,6 +532,10 @@
     "table": {
       "name": "Name",
       "size": "Größe"
+    },
+    "markdown_view_mode": {
+      "preview": "Vorschau",
+      "code": "Code"
     }
   },
   "badges": {
diff --git a/i18n/locales/en.json b/i18n/locales/en.json
index dae801ece6..07df690dc0 100644
--- a/i18n/locales/en.json
+++ b/i18n/locales/en.json
@@ -550,6 +550,10 @@
     "table": {
       "name": "Name",
       "size": "Size"
+    },
+    "markdown_view_mode": {
+      "preview": "preview",
+      "code": "code"
     }
   },
   "badges": {
diff --git a/i18n/locales/es.json b/i18n/locales/es.json
index 57984a8531..57707b5b61 100644
--- a/i18n/locales/es.json
+++ b/i18n/locales/es.json
@@ -535,6 +535,10 @@
     "table": {
       "name": "Nombre",
       "size": "Tamaño"
+    },
+    "markdown_view_mode": {
+      "preview": "vista previa",
+      "code": "código"
     }
   },
   "badges": {
diff --git a/i18n/locales/fr-FR.json b/i18n/locales/fr-FR.json
index 69a061e1ef..09e967069e 100644
--- a/i18n/locales/fr-FR.json
+++ b/i18n/locales/fr-FR.json
@@ -537,6 +537,10 @@
     "table": {
       "name": "Nom",
       "size": "Taille"
+    },
+    "markdown_view_mode": {
+      "preview": "aperçu",
+      "code": "code"
     }
   },
   "badges": {
diff --git a/i18n/locales/it-IT.json b/i18n/locales/it-IT.json
index 33b87dc3c2..611a168002 100644
--- a/i18n/locales/it-IT.json
+++ b/i18n/locales/it-IT.json
@@ -537,6 +537,10 @@
     "table": {
       "name": "Nome",
       "size": "Dimensione"
+    },
+    "markdown_view_mode": {
+      "preview": "anteprima",
+      "code": "codice"
     }
   },
   "filters": {
diff --git a/i18n/locales/ja-JP.json b/i18n/locales/ja-JP.json
index c4a2433fae..5526ed51e1 100644
--- a/i18n/locales/ja-JP.json
+++ b/i18n/locales/ja-JP.json
@@ -537,6 +537,10 @@
     "table": {
       "name": "名前",
       "size": "サイズ"
+    },
+    "markdown_view_mode": {
+      "preview": "プレビュー",
+      "code": "コード"
     }
   },
   "badges": {
diff --git a/i18n/locales/zh-CN.json b/i18n/locales/zh-CN.json
index df3b402602..e6801b3910 100644
--- a/i18n/locales/zh-CN.json
+++ b/i18n/locales/zh-CN.json
@@ -546,6 +546,10 @@
     "table": {
       "name": "名称",
       "size": "大小"
+    },
+    "markdown_view_mode": {
+      "preview": "预览",
+      "code": "代码"
     }
   },
   "badges": {
diff --git a/lunaria/files/ar.json b/lunaria/files/ar.json
index ef1feec9de..c858a3cb18 100644
--- a/lunaria/files/ar.json
+++ b/lunaria/files/ar.json
@@ -532,6 +532,10 @@
     "table": {
       "name": "الاسم",
       "size": "الحجم"
+    },
+    "markdown_view_mode": {
+      "preview": "معاينة",
+      "code": "الكود"
     }
   },
   "badges": {
diff --git a/lunaria/files/de-DE.json b/lunaria/files/de-DE.json
index bf1390d3d2..72bd00da77 100644
--- a/lunaria/files/de-DE.json
+++ b/lunaria/files/de-DE.json
@@ -532,6 +532,10 @@
     "table": {
       "name": "Name",
       "size": "Größe"
+    },
+    "markdown_view_mode": {
+      "preview": "Vorschau",
+      "code": "Code"
     }
   },
   "badges": {
diff --git a/lunaria/files/en-US.json b/lunaria/files/en-US.json
index dae801ece6..07df690dc0 100644
--- a/lunaria/files/en-US.json
+++ b/lunaria/files/en-US.json
@@ -550,6 +550,10 @@
     "table": {
       "name": "Name",
       "size": "Size"
+    },
+    "markdown_view_mode": {
+      "preview": "preview",
+      "code": "code"
     }
   },
   "badges": {
diff --git a/lunaria/files/es-419.json b/lunaria/files/es-419.json
index 08d6ecbd6d..3a8d98ed97 100644
--- a/lunaria/files/es-419.json
+++ b/lunaria/files/es-419.json
@@ -535,6 +535,10 @@
     "table": {
       "name": "Nombre",
       "size": "Tamaño"
+    },
+    "markdown_view_mode": {
+      "preview": "vista previa",
+      "code": "código"
     }
   },
   "badges": {
diff --git a/lunaria/files/es-ES.json b/lunaria/files/es-ES.json
index 57984a8531..57707b5b61 100644
--- a/lunaria/files/es-ES.json
+++ b/lunaria/files/es-ES.json
@@ -535,6 +535,10 @@
     "table": {
       "name": "Nombre",
       "size": "Tamaño"
+    },
+    "markdown_view_mode": {
+      "preview": "vista previa",
+      "code": "código"
     }
   },
   "badges": {
diff --git a/lunaria/files/fr-FR.json b/lunaria/files/fr-FR.json
index 69a061e1ef..09e967069e 100644
--- a/lunaria/files/fr-FR.json
+++ b/lunaria/files/fr-FR.json
@@ -537,6 +537,10 @@
     "table": {
       "name": "Nom",
       "size": "Taille"
+    },
+    "markdown_view_mode": {
+      "preview": "aperçu",
+      "code": "code"
     }
   },
   "badges": {
diff --git a/lunaria/files/it-IT.json b/lunaria/files/it-IT.json
index 33b87dc3c2..611a168002 100644
--- a/lunaria/files/it-IT.json
+++ b/lunaria/files/it-IT.json
@@ -537,6 +537,10 @@
     "table": {
       "name": "Nome",
       "size": "Dimensione"
+    },
+    "markdown_view_mode": {
+      "preview": "anteprima",
+      "code": "codice"
     }
   },
   "filters": {
diff --git a/lunaria/files/ja-JP.json b/lunaria/files/ja-JP.json
index c4a2433fae..5526ed51e1 100644
--- a/lunaria/files/ja-JP.json
+++ b/lunaria/files/ja-JP.json
@@ -537,6 +537,10 @@
     "table": {
       "name": "名前",
       "size": "サイズ"
+    },
+    "markdown_view_mode": {
+      "preview": "プレビュー",
+      "code": "コード"
     }
   },
   "badges": {
diff --git a/lunaria/files/zh-CN.json b/lunaria/files/zh-CN.json
index df3b402602..e6801b3910 100644
--- a/lunaria/files/zh-CN.json
+++ b/lunaria/files/zh-CN.json
@@ -546,6 +546,10 @@
     "table": {
       "name": "名称",
       "size": "大小"
+    },
+    "markdown_view_mode": {
+      "preview": "预览",
+      "code": "代码"
     }
   },
   "badges": {
diff --git a/server/api/registry/file/[...pkg].get.ts b/server/api/registry/file/[...pkg].get.ts
index 028469e439..b7c36a4167 100644
--- a/server/api/registry/file/[...pkg].get.ts
+++ b/server/api/registry/file/[...pkg].get.ts
@@ -1,5 +1,6 @@
 import * as v from 'valibot'
 import { PackageFileQuerySchema } from '#shared/schemas/package'
+import type { ReadmeResponse } from '#shared/types/readme'
 import {
   CACHE_MAX_AGE_ONE_YEAR,
   ERROR_PACKAGE_VERSION_AND_FILE_FAILED,
@@ -166,6 +167,18 @@ export default defineCachedEventHandler(
         resolveRelative,
       })
 
+      let markdownHtml: ReadmeResponse | undefined
+      if (language === 'markdown') {
+        // Best-effort: markdown preview is optional; never block code view
+        try {
+          const packageData = await fetchNpmPackage(rawPackageName)
+          const repoInfo = parseRepositoryInfo(packageData.repository)
+          markdownHtml = await renderReadmeHtml(content, rawPackageName, repoInfo)
+        } catch {
+          markdownHtml = undefined
+        }
+      }
+
       return {
         package: packageName,
         version,
@@ -174,6 +187,7 @@ export default defineCachedEventHandler(
         content,
         html,
         lines: content.split('\n').length,
+        markdownHtml,
       }
     } catch (error: unknown) {
       handleApiError(error, {
diff --git a/shared/types/npm-registry.ts b/shared/types/npm-registry.ts
index 624acc5e47..8722201f64 100644
--- a/shared/types/npm-registry.ts
+++ b/shared/types/npm-registry.ts
@@ -7,6 +7,7 @@
  */
 
 import type { PackumentVersion } from '@npm/types'
+import type { ReadmeResponse } from './readme'
 
 // Re-export official npm types for packument/manifest
 export type {
@@ -325,4 +326,5 @@ export interface PackageFileContentResponse {
   content: string
   html: string
   lines: number
+  markdownHtml?: ReadmeResponse
 }