good docs

package.json

@@ -143,7 +143,11 @@
     "knex": "^3.1.0",
     "lucide-svelte": "^0.561.0",
     "marked": "^17.0.1",
+    "marked-alert": "^2.1.2",
+    "marked-custom-heading-id": "^2.0.16",
+    "marked-gfm-heading-id": "^4.1.3",
     "marked-highlight": "^2.2.3",
+    "marked-plaintify": "^1.1.1",
     "mobile-detect": "^1.4.5",
     "mode-watcher": "^1.1.0",
     "moment": "^2.30.1",

src/lib/marked.ts

@@ -1,41 +1,45 @@
-import { marked } from "marked";
+import { Marked } from "marked";
 import { markedHighlight } from "marked-highlight";
+import markedPlaintify from "marked-plaintify";
+import customHeadingId from "marked-custom-heading-id";
+import markedAlert from "marked-alert";
 import hljs from "highlight.js";
 
-/**
- * Configure marked with syntax highlighting
- * Uses highlight.js for code block syntax highlighting
- */
-function configureMarked() {
-  // Configure marked with highlight.js
-  marked.use(
-    markedHighlight({
-      langPrefix: "hljs language-",
-      highlight(code: string, lang: string) {
-        const language = hljs.getLanguage(lang) ? lang : "plaintext";
-        return hljs.highlight(code, { language }).value;
-      },
-    }),
-  );
+// Create dedicated instances for each use case to avoid cross-contamination
+const markedHTML = new Marked();
+const markedText = new Marked();
 
-  // Custom renderer to open links in new tab
-  const renderer = new marked.Renderer();
-  renderer.link = function ({ href, title, tokens }: { href: string; title?: string | null; tokens: any[] }) {
-    const titleAttr = title ? ` title="${title}"` : "";
-    const text = this.parser.parseInline(tokens);
-    return `<a href="${href}"${titleAttr} target="_blank" rel="noopener noreferrer">${text}</a>`;
-  };
+// Configure HTML instance with syntax highlighting
+markedHTML.use(customHeadingId());
+markedHTML.use(markedAlert());
+markedHTML.use(
+  markedHighlight({
+    langPrefix: "hljs language-",
+    highlight(code: string, lang: string) {
+      const language = hljs.getLanguage(lang) ? lang : "plaintext";
+      return hljs.highlight(code, { language }).value;
+    },
+  }),
+);
+markedHTML.use({
+  renderer: {
+    link({ href, title, tokens }: { href: string; title?: string | null; tokens: any[] }) {
+      const titleAttr = title ? ` title="${title}"` : "";
+      const text = this.parser.parseInline(tokens);
+      return `<a href="${href}"${titleAttr} target="_blank" rel="noopener noreferrer">${text}</a>`;
+    },
+  },
+});
+markedHTML.setOptions({
+  breaks: true,
+  gfm: true,
+});
 
-  marked.setOptions({
-    breaks: true, // Convert line breaks to <br>
-    gfm: true, // Enable GitHub Flavored Markdown
-    renderer: renderer,
-  });
-}
+// Configure text instance for plain text conversion
+markedText.use(markedPlaintify());
 
 /**
  * Convert markdown to HTML with syntax highlighting
- * Initializes marked configuration on first use for optimal performance
  *
  * @param markdown - The markdown string to convert
  * @returns HTML string with syntax-highlighted code blocks
@@ -46,13 +50,24 @@ function configureMarked() {
  * // Returns: <pre><code class="hljs language-javascript">...</code></pre>
  * ```
  */
-let isConfigured = false;
-
 export default function mdToHTML(markdown: string): string {
-  if (!isConfigured) {
-    configureMarked();
-    isConfigured = true;
-  }
+  return markedHTML.parse(markdown, { async: false }) as string;
+}
 
-  return marked.parse(markdown) as string;
+/**
+ * Convert markdown to plain text
+ * Strips all markdown syntax and returns clean text
+ *
+ * @param markdown - The markdown string to convert
+ * @returns Plain text string with markdown syntax removed
+ *
+ * @example
+ * ```typescript
+ * const text = mdToText('# Hello **World**');
+ * // Returns: 'Hello World'
+ * ```
+ */
+export function mdToText(markdown: string): string {
+  const text = markedText.parse(markdown, { async: false }) as string;
+  return text.replace(/\s+/g, " ").trim();
 }

src/lib/server/docs-search.ts

@@ -4,9 +4,8 @@
  */
 
 import FlexSearch from "flexsearch";
-import { marked } from "marked";
-import striptags from "striptags";
 import { redisConnection } from "$lib/server/redisConnector";
+import { mdToText } from "$lib/marked";
 import type { DocsSearchDocument, DocsSearchResult, DocsSearchIndexData } from "$lib/types/docs-search";
 import { getDocsConfig, getMarkdownContent, getAllPages } from "../../routes/(docs)/docs/docs-utils.server";
 
@@ -17,16 +16,6 @@ const REDIS_DOCS_KEY = "kener-docs:search:documents";
 let searchIndex: any = null;
 let documentsMap: Map<string, DocsSearchDocument> = new Map();
 
-/**
- * Convert markdown to plain text using marked and striptags
- */
-function stripMarkdown(content: string): string {
-  // Convert markdown to HTML
-  const html = marked.parse(content, { async: false }) as string;
-  // Strip HTML tags and normalize whitespace
-  return striptags(html).replace(/\s+/g, " ").trim();
-}
-
 /**
  * Create a search excerpt around the matching term
  */
@@ -51,7 +40,7 @@ function createExcerpt(content: string, query: string, maxLength: number = 150):
 }
 
 /**
- * Create slug from heading text (same logic as addHeadingIds in docs-utils)
+ * Create slug from heading text (same logic as marked-gfm-heading-id)
  */
 function createHeadingSlug(text: string): string {
   return text
@@ -149,7 +138,7 @@ export async function buildSearchIndex(): Promise<void> {
     for (const page of group.pages) {
       const markdownContent = getMarkdownContent(page.slug);
       if (markdownContent) {
-        const plainContent = stripMarkdown(markdownContent);
+        const plainContent = mdToText(markdownContent);
         const doc: DocsSearchDocument = {
           id: page.slug,
           title: page.title,

src/routes/(docs)/+layout.svelte

@@ -2,6 +2,8 @@
   import "../layout.css";
   import "../kener.css";
   import "../docs.css";
+  import "../prose.css";
+  import "highlight.js/styles/github-dark.css";
   import { ModeWatcher } from "mode-watcher";
   import { resolve } from "$app/paths";
   import { Toaster } from "$lib/components/ui/sonner/index.js";

src/routes/(docs)/docs/(with-sidebar)/+layout.svelte

@@ -33,23 +33,19 @@
   <div class="mx-auto flex max-w-[1400px] pt-24">
     <!-- Mobile sidebar overlay -->
     {#if isMobileMenuOpen}
-      <div
-        class="fixed inset-0 top-24 z-[35] bg-black/50 lg:hidden"
-        onclick={closeMobileMenu}
-        role="presentation"
-      ></div>
+      <div class="fixed inset-0 top-24 z-35 bg-black/50 lg:hidden" onclick={closeMobileMenu} role="presentation"></div>
     {/if}
 
     <!-- Sidebar -->
     <aside
-      class="bg-background border-border fixed top-24 bottom-0 left-0 z-40 w-[280px] -translate-x-full overflow-y-auto border-r transition-transform duration-300 ease-in-out lg:translate-x-0"
+      class="bg-background fixed top-24 bottom-0 left-0 z-40 w-[200px] -translate-x-full overflow-y-auto transition-transform duration-300 ease-in-out lg:translate-x-0"
       class:translate-x-0={isMobileMenuOpen}
     >
       <DocsSidebar config={data.config} currentSlug={data.currentSlug} onNavigate={closeMobileMenu} />
     </aside>
 
     <!-- Main content -->
-    <div class="min-w-0 flex-1 p-6 px-8 lg:ml-[280px] lg:p-8 lg:px-12">
+    <div class="min-w-0 flex-1 p-6 px-8 lg:ml-[200px] lg:p-8 lg:px-12">
       {@render children()}
     </div>
   </div>

src/routes/(docs)/docs/(with-sidebar)/[...slug]/+page.server.ts

@@ -1,5 +1,5 @@
 import type { PageServerLoad } from "./$types";
-import { getDocsPageData, addHeadingIds, extractTableOfContents, docExists } from "../../docs-utils.server";
+import { getDocsPageData, extractTableOfContents, docExists } from "../../docs-utils.server";
 import { error } from "@sveltejs/kit";
 import mdToHTML from "$lib/marked";
 
@@ -21,11 +21,8 @@ export const load: PageServerLoad = async ({ params }) => {
     });
   }
 
-  // Convert markdown to HTML
-  let htmlContent = mdToHTML(pageData.content);
-
-  // Add IDs to headings for anchor links
-  htmlContent = addHeadingIds(htmlContent);
+  // Convert markdown to HTML (heading IDs are added by marked-gfm-heading-id)
+  const htmlContent = mdToHTML(pageData.content);
 
   // Extract table of contents
   const tableOfContents = extractTableOfContents(htmlContent);