@limcpf/everything-is-a-markdown 0.6.0 → 0.6.1

package/README.ko.md

@@ -78,6 +78,13 @@ const config = {
     pathBase: "/blog",
     defaultOgImage: "/assets/og.png",
   },
+  markdown: {
+    mermaid: {
+      enabled: true,
+      cdnUrl: "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js",
+      theme: "default",
+    },
+  },
 };
 
 export default config;
@@ -173,6 +180,37 @@ title: Work In Progress
 ---
 ```
 
+## Mermaid 다이어그램 지원
+
+코드 블록의 언어를 `mermaid`로 작성하면 브라우저에서 Mermaid 다이어그램으로 렌더링합니다.
+
+````md
+```mermaid
+flowchart LR
+  A --> B
+```
+````
+
+문서 전환 시에도 해당 블록을 다시 렌더링합니다. 설정에서 Mermaid를 비활성화하면 소스 코드 블록 그대로 표시됩니다.
+
+`blog.config.ts`에서 설정:
+
+```ts
+markdown: {
+  mermaid: {
+    enabled: true, // false면 코드 블록만 표시
+    cdnUrl: "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js", // http/https 또는 /, ./, ../ 경로
+    theme: "default", // mermaid.initialize({ theme }) 값
+  },
+},
+```
+
+유효성 검증 및 런타임 가드레일:
+
+- `markdown.mermaid.cdnUrl`에 잘못된 값(예: `javascript:`)이 들어오면 빌드 시 기본 CDN URL로 자동 폴백합니다.
+- `markdown.mermaid.theme`이 유효한 식별자 형식이 아니면 빌드 시 `default`로 자동 폴백합니다.
+- 런타임 로더는 실패 후 남은 Mermaid 스크립트를 정리하고, 중복 삽입을 피하며, 다음 렌더에서 재시도합니다.
+
 ## bunx 실행 (선택)
 
 ```bash

package/README.md

@@ -78,6 +78,13 @@ const config = {
     pathBase: "/blog",
     defaultOgImage: "/assets/og.png",
   },
+  markdown: {
+    mermaid: {
+      enabled: true,
+      cdnUrl: "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js",
+      theme: "default",
+    },
+  },
 };
 
 export default config;
@@ -173,6 +180,37 @@ title: Work In Progress
 ---
 ```
 
+## Mermaid Diagram Support
+
+This project supports Mermaid diagrams written as fenced code blocks:
+
+````
+```mermaid
+flowchart LR
+  A --> B
+```
+````
+
+Rendering happens in the browser on first load and when navigating to another document. If Mermaid is disabled in config or CDN loading fails, the source block is shown as-is and a warning message appears.
+
+Configuration options (`blog.config.ts`):
+
+```ts
+markdown: {
+  mermaid: {
+    enabled: true, // false to keep only source blocks
+    cdnUrl: "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js", // CDN URL (http/https or /, ./, ../)
+    theme: "default", // passed to mermaid.initialize({ theme })
+  },
+},
+```
+
+Validation and runtime guardrails:
+
+- Invalid `markdown.mermaid.cdnUrl` values (for example `javascript:`) automatically fall back to the default CDN URL at build time.
+- Invalid `markdown.mermaid.theme` values automatically fall back to `default` at build time.
+- Runtime loader removes stale Mermaid script tags after failures, avoids duplicate injection, and retries cleanly on the next render.
+
 ## bunx (Optional)
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limcpf/everything-is-a-markdown",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "license": "MIT",
   "private": false,
   "type": "module",

package/src/build.ts

@@ -868,6 +868,7 @@ function buildManifest(docs: DocRecord[], tree: TreeNode[], options: BuildOption
     siteTitle: resolveSiteTitle(options),
     pathBase: options.seo?.pathBase ?? "",
     defaultBranch: DEFAULT_BRANCH,
+    mermaid: options.mermaid,
     branches,
     ui: {
       newWithinDays: options.newWithinDays,

package/src/config.ts

@@ -25,8 +25,53 @@ const DEFAULTS = {
   imagePolicy: "omit-local" as const,
   gfm: true,
   shikiTheme: "github-dark",
+  mermaid: {
+    enabled: true,
+    cdnUrl: "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js",
+    theme: "default",
+  },
 };
 
+const MERMAID_URL_MAX_LENGTH = 1024;
+const MERMAID_THEME_PATTERN = /^[a-zA-Z][a-zA-Z0-9._-]*$/;
+const MERMAID_CDN_URL_PATTERN = /^(https?:\/\/|\/|\.{1,2}\/)[^\s"'><]+$/;
+
+function normalizeMermaidEnabled(value: unknown): boolean {
+  return typeof value === "boolean" ? value : DEFAULTS.mermaid.enabled;
+}
+
+function normalizeMermaidCdnUrl(value: unknown): string {
+  if (typeof value !== "string") {
+    return DEFAULTS.mermaid.cdnUrl;
+  }
+
+  const normalized = value.trim();
+  if (!normalized) {
+    return DEFAULTS.mermaid.cdnUrl;
+  }
+
+  if (normalized.length > MERMAID_URL_MAX_LENGTH || !MERMAID_CDN_URL_PATTERN.test(normalized)) {
+    console.warn(`[config] invalid mermaid.cdnUrl: ${JSON.stringify(value)}. fallback to default ${JSON.stringify(DEFAULTS.mermaid.cdnUrl)}.`);
+    return DEFAULTS.mermaid.cdnUrl;
+  }
+
+  return normalized;
+}
+
+function normalizeMermaidTheme(value: unknown): string {
+  if (typeof value !== "string") {
+    return DEFAULTS.mermaid.theme;
+  }
+
+  const normalized = value.trim();
+  if (!MERMAID_THEME_PATTERN.test(normalized)) {
+    console.warn(`[config] invalid mermaid.theme: ${JSON.stringify(value)}. fallback to default ${JSON.stringify(DEFAULTS.mermaid.theme)}.`);
+    return DEFAULTS.mermaid.theme;
+  }
+
+  return normalized;
+}
+
 export function parseCliArgs(argv: string[]): CliArgs {
   const [first] = argv;
   const command = first === "build" || first === "dev" || first === "clean" ? first : "build";
@@ -250,6 +295,11 @@ export function resolveBuildOptions(
     imagePolicy: userConfig.markdown?.images ?? DEFAULTS.imagePolicy,
     gfm: userConfig.markdown?.gfm ?? DEFAULTS.gfm,
     shikiTheme: userConfig.markdown?.highlight?.theme ?? DEFAULTS.shikiTheme,
+    mermaid: {
+      enabled: normalizeMermaidEnabled(userConfig.markdown?.mermaid?.enabled),
+      cdnUrl: normalizeMermaidCdnUrl(userConfig.markdown?.mermaid?.cdnUrl),
+      theme: normalizeMermaidTheme(userConfig.markdown?.mermaid?.theme),
+    },
     seo,
   };
 }

package/src/markdown.ts

@@ -16,6 +16,7 @@ export interface MarkdownRenderer {
 }
 
 const FENCE_LANG_RE = /^```([\w-+#.]+)/gm;
+const MERMAID_LANG = "mermaid";
 type RenderRule = NonNullable<MarkdownIt["renderer"]["rules"]["fence"]>;
 type RenderRuleArgs = Parameters<RenderRule>;
 type RuleTokens = RenderRuleArgs[0];
@@ -28,6 +29,15 @@ function escapeMarkdownLabel(input: string): string {
   return input.replace(/[\[\]]/g, "");
 }
 
+function escapeHtmlText(input: string): string {
+  return String(input)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
 function parseWikiInner(inner: string): { target: string; label?: string } {
   const [target, label] = inner.split("|").map((part) => part.trim());
   return { target, label: label || undefined };
@@ -107,6 +117,9 @@ async function loadFenceLanguages<L extends string, T extends string>(
       break;
     }
     if (match[1]) {
+      if (match[1].toLowerCase() === MERMAID_LANG) {
+        continue;
+      }
       langs.add(match[1].toLowerCase());
     }
   }
@@ -152,6 +165,25 @@ function createMarkdownIt<L extends string, T extends string>(
     const lang = parts[0]?.toLowerCase() || "text";
     const fileName = parts.slice(1).join(" ") || null;
 
+    if (lang === MERMAID_LANG) {
+      const source = escapeHtmlText(token.content);
+      const filename = fileName ? escapeHtmlAttr(fileName) : MERMAID_LANG;
+      return `<div class="code-block mermaid-block">
+        <div class="code-header">
+          <div class="code-dots">
+            <span class="dot dot-red"></span>
+            <span class="dot dot-yellow"></span>
+            <span class="dot dot-green"></span>
+          </div>
+          <span class="code-filename">${filename}</span>
+          <button class="code-copy" title="Copy code" data-code="${escapeHtmlAttr(token.content)}">
+            <span class="material-symbols-outlined">content_copy</span>
+          </button>
+        </div>
+        <pre class="mermaid">${source}</pre>
+      </div>`;
+    }
+
     let codeHtml: string;
     try {
       codeHtml = highlighter.codeToHtml(token.content, {

package/src/runtime/app.css

@@ -1098,6 +1098,35 @@ body.mobile-toggle-left .mobile-menu-toggle {
   tab-size: 2;
 }
 
+.viewer-content .code-block pre.mermaid {
+  margin: 0;
+  border: none;
+  border-radius: 0;
+  padding: 0;
+  background: transparent !important;
+  color: inherit;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.viewer-content .code-block pre.mermaid svg {
+  width: 100%;
+  height: auto;
+  display: block;
+}
+
+.viewer-content .mermaid-render-error {
+  margin: 0;
+  padding: 10px 16px;
+  border: 1px solid rgba(244, 63, 94, 0.35);
+  border-radius: 0 0 8px 8px;
+  border-top: none;
+  color: var(--latte-red);
+  background: rgba(244, 63, 94, 0.08);
+  font-size: 0.84rem;
+  line-height: 1.45;
+}
+
 .viewer-content pre {
   position: relative;
   margin: 1.5rem 0;

package/src/runtime/app.js

@@ -15,6 +15,19 @@ const DEFAULT_SITE_TITLE = "File-System Blog";
 const BRANCH_KEY = "fsblog.branch";
 const FOCUSABLE_SELECTOR =
   'a[href], button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+const MERMAID_CDN = "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js";
+const MERMAID_DEFAULT_THEME = "default";
+const MERMAID_SELECTOR = "pre.mermaid";
+const MERMAID_ERROR_CLASS = "mermaid-render-error";
+const MERMAID_THEME_VALIDATION_RE = /^[a-zA-Z][a-zA-Z0-9._-]*$/;
+const MERMAID_URL_VALIDATION_RE = /^(https?:\/\/|\/|\.{1,2}\/)[^\s"'<>]+$/;
+const mermaidRuntime = {
+  initialized: false,
+  loadingPromise: null,
+  scriptElement: null,
+  lastCdnUrl: "",
+  lastTheme: "",
+};
 
 function escapeHtmlAttr(input) {
   return String(input)
@@ -24,6 +37,212 @@ function escapeHtmlAttr(input) {
     .replace(/>/g, "&gt;");
 }
 
+function resolveMermaidConfig(manifest) {
+  const mermaid = manifest?.mermaid;
+  return {
+    enabled: mermaid?.enabled !== false,
+    cdnUrl:
+      typeof mermaid?.cdnUrl === "string" && mermaid.cdnUrl.trim()
+        ? mermaid.cdnUrl.trim()
+        : MERMAID_CDN,
+    theme:
+      typeof mermaid?.theme === "string" &&
+      MERMAID_THEME_VALIDATION_RE.test(mermaid.theme.trim())
+        ? mermaid.theme.trim()
+        : MERMAID_DEFAULT_THEME,
+  };
+}
+
+function toAbsoluteUrl(value) {
+  try {
+    return new URL(value, window.location.href).href;
+  } catch {
+    return value;
+  }
+}
+
+function normalizeMermaidTheme(value) {
+  const normalized = typeof value === "string" ? value.trim() : "";
+  if (!normalized || !MERMAID_THEME_VALIDATION_RE.test(normalized)) {
+    return MERMAID_DEFAULT_THEME;
+  }
+  return normalized;
+}
+
+function normalizeMermaidUrl(value) {
+  const normalized = typeof value === "string" ? value.trim() : "";
+  if (!normalized || !MERMAID_URL_VALIDATION_RE.test(normalized)) {
+    return MERMAID_CDN;
+  }
+  return normalized;
+}
+
+function createMermaidLoadError(message) {
+  const paragraph = document.createElement("p");
+  paragraph.className = MERMAID_ERROR_CLASS;
+  paragraph.textContent = message;
+  return paragraph;
+}
+
+function removeMermaidErrorMessage(container) {
+  if (!(container instanceof HTMLElement)) {
+    return;
+  }
+
+  for (const message of container.querySelectorAll(`.${MERMAID_ERROR_CLASS}`)) {
+    message.remove();
+  }
+}
+
+function showMermaidError(preview, message) {
+  if (!(preview instanceof HTMLElement) || !(preview.parentElement instanceof HTMLElement)) {
+    return;
+  }
+
+  removeMermaidErrorMessage(preview.parentElement);
+  preview.parentElement.appendChild(createMermaidLoadError(message));
+}
+
+function parseMermaidNodes() {
+  const contentEl = document.getElementById("viewer-content");
+  if (!(contentEl instanceof HTMLElement)) {
+    return [];
+  }
+
+  return Array.from(contentEl.querySelectorAll(MERMAID_SELECTOR));
+}
+
+function resetMermaidNodes(nodes) {
+  for (const node of nodes) {
+    node.removeAttribute("data-mermaid-rendered");
+    if (node.parentElement instanceof HTMLElement) {
+      removeMermaidErrorMessage(node.parentElement);
+    }
+  }
+}
+
+async function loadMermaidLibrary(config) {
+  if (!config.enabled) {
+    return null;
+  }
+
+  const normalized = {
+    ...config,
+    theme: normalizeMermaidTheme(config.theme),
+    cdnUrl: normalizeMermaidUrl(config.cdnUrl),
+  };
+
+  if (window.mermaid) {
+    if (!mermaidRuntime.initialized || mermaidRuntime.lastTheme !== normalized.theme) {
+      window.mermaid.initialize({
+        startOnLoad: false,
+        theme: normalized.theme,
+      });
+      mermaidRuntime.initialized = true;
+      mermaidRuntime.lastTheme = normalized.theme;
+    }
+    return window.mermaid;
+  }
+
+  if (mermaidRuntime.loadingPromise) {
+    return mermaidRuntime.loadingPromise;
+  }
+
+  const expectedAbsoluteUrl = toAbsoluteUrl(normalized.cdnUrl);
+  const existingScript = document.getElementById("mermaid-runtime");
+  if (existingScript instanceof HTMLScriptElement) {
+    // 이전 로드가 비정상 종료된 스크립트 잔존을 막기 위해 재시도 전에 정리한다.
+    existingScript.remove();
+    mermaidRuntime.scriptElement = null;
+    mermaidRuntime.initialized = false;
+    mermaidRuntime.lastTheme = "";
+    mermaidRuntime.lastCdnUrl = "";
+  }
+
+  mermaidRuntime.loadingPromise = new Promise((resolve, reject) => {
+    let script = mermaidRuntime.scriptElement;
+    if (!(script instanceof HTMLScriptElement)) {
+      script = document.createElement("script");
+      script.id = "mermaid-runtime";
+      script.src = normalized.cdnUrl;
+      script.async = true;
+      script.crossOrigin = "anonymous";
+      mermaidRuntime.scriptElement = script;
+      mermaidRuntime.lastCdnUrl = expectedAbsoluteUrl;
+    }
+
+    const finalize = (error) => {
+      mermaidRuntime.loadingPromise = null;
+      if (error) {
+        if (mermaidRuntime.scriptElement instanceof HTMLScriptElement) {
+          mermaidRuntime.scriptElement.remove();
+          mermaidRuntime.scriptElement = null;
+        }
+        mermaidRuntime.initialized = false;
+        mermaidRuntime.lastTheme = "";
+        mermaidRuntime.lastCdnUrl = "";
+        reject(error);
+        return;
+      }
+      resolve(window.mermaid ?? null);
+    };
+
+    script.addEventListener("load", () => {
+      if (window.mermaid && (!mermaidRuntime.initialized || mermaidRuntime.lastTheme !== normalized.theme)) {
+        window.mermaid.initialize({
+          startOnLoad: false,
+          theme: normalized.theme,
+        });
+        mermaidRuntime.initialized = true;
+        mermaidRuntime.lastTheme = normalized.theme;
+      }
+      finalize();
+    });
+    script.addEventListener("error", () => {
+      finalize(new Error(`Mermaid 라이브러리 로드 실패: ${normalized.cdnUrl}`));
+    });
+
+    if (!script.isConnected) {
+      document.head.appendChild(script);
+    }
+  });
+
+  return mermaidRuntime.loadingPromise;
+}
+
+async function renderMermaidBlocks(config) {
+  const blocks = parseMermaidNodes();
+  if (blocks.length === 0) {
+    return;
+  }
+
+  resetMermaidNodes(blocks);
+
+  try {
+    const mermaid = await loadMermaidLibrary(config);
+    if (!mermaid) {
+      for (const block of blocks) {
+        showMermaidError(block, "Mermaid 렌더링이 비활성화되어 코드 블록을 그대로 표시합니다.");
+      }
+      return;
+    }
+    if (typeof mermaid.run === "function") {
+      await mermaid.run({ nodes: blocks });
+      return;
+    }
+    if (typeof mermaid.init === "function") {
+      await mermaid.init({ startOnLoad: false }, blocks);
+      return;
+    }
+    throw new Error("Mermaid 렌더러 API가 존재하지 않습니다.");
+  } catch (error) {
+    const message = `Mermaid 렌더링 실패: ${error instanceof Error ? error.message : String(error)}`;
+    for (const block of blocks) {
+      showMermaidError(block, message);
+    }
+  }
+}
+
 function toSafeUrlPath(input) {
   const value = String(input);
   return value
@@ -1253,6 +1472,7 @@ async function start() {
     }
     manifest = await manifestRes.json();
   }
+  const mermaidConfig = resolveMermaidConfig(manifest);
   const pathBase = normalizePathBase(manifest.pathBase);
   const siteTitle = resolveSiteTitle(manifest);
   const defaultBranch = normalizeBranch(manifest.defaultBranch) || DEFAULT_BRANCH;
@@ -1445,6 +1665,7 @@ async function start() {
         metaEl.innerHTML = renderMeta(doc);
         updateBacklinks(doc);
         navEl.innerHTML = renderNav(view.docs, view.docIndexById, id, pathBase);
+        await renderMermaidBlocks(mermaidConfig);
         document.title = composeDocumentTitle(doc.title, siteTitle);
         if (viewerEl instanceof HTMLElement) {
           viewerEl.scrollTo(0, 0);
@@ -1470,6 +1691,7 @@ async function start() {
 
       updateBacklinks(doc);
       navEl.innerHTML = renderNav(view.docs, view.docIndexById, id, pathBase);
+      await renderMermaidBlocks(mermaidConfig);
 
       document.title = composeDocumentTitle(doc.title, siteTitle);
       if (viewerEl instanceof HTMLElement) {

package/src/types.ts

@@ -56,6 +56,11 @@ export interface UserConfig {
       engine?: "shiki";
       theme?: string;
     };
+    mermaid?: {
+      enabled?: boolean;
+      cdnUrl?: string;
+      theme?: string;
+    };
   };
   seo?: UserSeoConfig;
 }
@@ -73,6 +78,11 @@ export interface BuildOptions {
   imagePolicy: ImagePolicy;
   gfm: boolean;
   shikiTheme: string;
+  mermaid: {
+    enabled: boolean;
+    cdnUrl: string;
+    theme: string;
+  };
   seo: BuildSeoOptions | null;
 }
 
@@ -130,6 +140,11 @@ export interface Manifest {
   pathBase: string;
   defaultBranch: string;
   branches: string[];
+  mermaid: {
+    enabled: boolean;
+    cdnUrl: string;
+    theme: string;
+  };
   ui: {
     newWithinDays: number;
     recentLimit: number;