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

package/README.ko.md

@@ -42,6 +42,28 @@ bun run blog [build|dev|clean] [options]
 - `--recent-limit <n>`: Recent 폴더 문서 수 제한 (정수 `>= 1`, 기본 `5`)
 - `--port <n>`: 개발 서버 포트 (기본 `3000`)
 
+## Markdown Lint (publish 전용)
+
+`publish: true` 문서만 대상으로 Markdown lint를 실행하고, 결과를 JSON 파일로 저장할 수 있습니다.
+내부적으로 `markdownlint` Node API를 사용합니다.
+
+```bash
+bun run lint:md:publish -- --out-dir ./reports
+```
+
+엄격 모드(`--strict`)를 추가하면 위반이 있을 때 종료 코드 `1`을 반환합니다.
+
+```bash
+bun run lint:md:publish -- --out-dir ./reports --strict
+```
+
+옵션:
+
+- `--out-dir <path>`: 리포트 출력 디렉터리 (필수)
+- `--strict`: 위반이 있으면 종료 코드 `1`
+- `--vault <path>`: Markdown 루트 디렉터리 재지정 (선택)
+- `--exclude <glob>`: 제외 패턴 추가 (반복 가능)
+
 ## 설정 파일 (`blog.config.ts`)
 
 SEO/UI/정적 파일 설정은 config 파일에서 관리할 수 있습니다.
@@ -56,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;
@@ -151,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

@@ -42,6 +42,28 @@ Common options:
 - `--recent-limit <n>`: Recent folder item limit (integer `>= 1`, default `5`)
 - `--port <n>`: Dev server port (default `3000`)
 
+## Markdown Lint (publish only)
+
+You can run Markdown lint only for `publish: true` documents and save results as a JSON report.
+Internally, this command uses the `markdownlint` Node API.
+
+```bash
+bun run lint:md:publish -- --out-dir ./reports
+```
+
+Add strict mode (`--strict`) to return exit code `1` when violations exist.
+
+```bash
+bun run lint:md:publish -- --out-dir ./reports --strict
+```
+
+Options:
+
+- `--out-dir <path>`: Report output directory (required)
+- `--strict`: Return exit code `1` when violations exist
+- `--vault <path>`: Override Markdown root directory (optional)
+- `--exclude <glob>`: Add exclude pattern (repeatable)
+
 ## Config File (`blog.config.ts`)
 
 Use a config file for SEO/UI/static assets.
@@ -56,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;
@@ -151,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/bun.lock

@@ -16,6 +16,7 @@
         "@types/markdown-it": "^14.1.2",
         "@types/picomatch": "^4.0.2",
         "bun-types": "^1.3.8",
+        "markdownlint": "^0.40.0",
       },
     },
   },
@@ -36,8 +37,12 @@
 
     "@shikijs/vscode-textmate": ["@shikijs/vscode-textmate@10.0.2", "", {}, "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg=="],
 
+    "@types/debug": ["@types/debug@4.1.12", "", { "dependencies": { "@types/ms": "*" } }, "sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ=="],
+
     "@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ=="],
 
+    "@types/katex": ["@types/katex@0.16.8", "", {}, "sha512-trgaNyfU+Xh2Tc+ABIb44a5AYUpicB3uwirOioeOkNPPbmgRNtcWyDeeFRzjPZENO9Vq8gvVqfhaaXWLlevVwg=="],
+
     "@types/linkify-it": ["@types/linkify-it@5.0.0", "", {}, "sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q=="],
 
     "@types/markdown-it": ["@types/markdown-it@14.1.2", "", { "dependencies": { "@types/linkify-it": "^5", "@types/mdurl": "^2" } }, "sha512-promo4eFwuiW+TfGxhi+0x3czqTYJkG8qB17ZUJiVF10Xm7NLVRSLUsfRTU/6h1e24VvRnXCx+hG7li58lkzog=="],
@@ -46,6 +51,8 @@
 
     "@types/mdurl": ["@types/mdurl@2.0.0", "", {}, "sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg=="],
 
+    "@types/ms": ["@types/ms@2.1.0", "", {}, "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA=="],
+
     "@types/node": ["@types/node@25.2.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-BkmoP5/FhRYek5izySdkOneRyXYN35I860MFAGupTdebyE66uZaR+bXLHq8k4DirE5DwQi3NuhvRU1jqTVwUrQ=="],
 
     "@types/picomatch": ["@types/picomatch@4.0.2", "", {}, "sha512-qHHxQ+P9PysNEGbALT8f8YOSHW0KJu6l2xU8DYY0fu/EmGxXdVnuTLvFUvBgPJMSqXq29SYHveejeAha+4AYgA=="],
@@ -54,20 +61,32 @@
 
     "@ungap/structured-clone": ["@ungap/structured-clone@1.3.0", "", {}, "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g=="],
 
+    "ansi-regex": ["ansi-regex@6.2.2", "", {}, "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg=="],
+
     "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],
 
     "bun-types": ["bun-types@1.3.8", "", { "dependencies": { "@types/node": "*" } }, "sha512-fL99nxdOWvV4LqjmC+8Q9kW3M4QTtTR1eePs94v5ctGqU8OeceWrSUaRw3JYb7tU3FkMIAjkueehrHPPPGKi5Q=="],
 
     "ccount": ["ccount@2.0.1", "", {}, "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg=="],
 
+    "character-entities": ["character-entities@2.0.2", "", {}, "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ=="],
+
     "character-entities-html4": ["character-entities-html4@2.1.0", "", {}, "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA=="],
 
     "character-entities-legacy": ["character-entities-legacy@3.0.0", "", {}, "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ=="],
 
+    "character-reference-invalid": ["character-reference-invalid@2.0.1", "", {}, "sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw=="],
+
     "chokidar": ["chokidar@4.0.3", "", { "dependencies": { "readdirp": "^4.0.1" } }, "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA=="],
 
     "comma-separated-tokens": ["comma-separated-tokens@2.0.3", "", {}, "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg=="],
 
+    "commander": ["commander@8.3.0", "", {}, "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww=="],
+
+    "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
+
+    "decode-named-character-reference": ["decode-named-character-reference@1.3.0", "", { "dependencies": { "character-entities": "^2.0.0" } }, "sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q=="],
+
     "dequal": ["dequal@2.0.3", "", {}, "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA=="],
 
     "devlop": ["devlop@1.1.0", "", { "dependencies": { "dequal": "^2.0.0" } }, "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA=="],
@@ -80,6 +99,8 @@
 
     "fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
 
+    "get-east-asian-width": ["get-east-asian-width@1.4.0", "", {}, "sha512-QZjmEOC+IT1uk6Rx0sX22V6uHWVwbdbxf1faPqJ1QhLdGgsRGCZoyaQBm/piRdJy/D2um6hM1UP7ZEeQ4EkP+Q=="],
+
     "gray-matter": ["gray-matter@4.0.3", "", { "dependencies": { "js-yaml": "^3.13.1", "kind-of": "^6.0.2", "section-matter": "^1.0.0", "strip-bom-string": "^1.0.0" } }, "sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q=="],
 
     "hast-util-to-html": ["hast-util-to-html@9.0.5", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "ccount": "^2.0.0", "comma-separated-tokens": "^2.0.0", "hast-util-whitespace": "^3.0.0", "html-void-elements": "^3.0.0", "mdast-util-to-hast": "^13.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "stringify-entities": "^4.0.0", "zwitch": "^2.0.4" } }, "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw=="],
@@ -88,34 +109,90 @@
 
     "html-void-elements": ["html-void-elements@3.0.0", "", {}, "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg=="],
 
+    "is-alphabetical": ["is-alphabetical@2.0.1", "", {}, "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ=="],
+
+    "is-alphanumerical": ["is-alphanumerical@2.0.1", "", { "dependencies": { "is-alphabetical": "^2.0.0", "is-decimal": "^2.0.0" } }, "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw=="],
+
+    "is-decimal": ["is-decimal@2.0.1", "", {}, "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A=="],
+
     "is-extendable": ["is-extendable@0.1.1", "", {}, "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw=="],
 
+    "is-hexadecimal": ["is-hexadecimal@2.0.1", "", {}, "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg=="],
+
     "js-yaml": ["js-yaml@3.14.2", "", { "dependencies": { "argparse": "^1.0.7", "esprima": "^4.0.0" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg=="],
 
+    "katex": ["katex@0.16.28", "", { "dependencies": { "commander": "^8.3.0" }, "bin": { "katex": "cli.js" } }, "sha512-YHzO7721WbmAL6Ov1uzN/l5mY5WWWhJBSW+jq4tkfZfsxmo1hu6frS0EOswvjBUnWE6NtjEs48SFn5CQESRLZg=="],
+
     "kind-of": ["kind-of@6.0.3", "", {}, "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw=="],
 
     "linkify-it": ["linkify-it@5.0.0", "", { "dependencies": { "uc.micro": "^2.0.0" } }, "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ=="],
 
     "markdown-it": ["markdown-it@14.1.0", "", { "dependencies": { "argparse": "^2.0.1", "entities": "^4.4.0", "linkify-it": "^5.0.0", "mdurl": "^2.0.0", "punycode.js": "^2.3.1", "uc.micro": "^2.1.0" }, "bin": { "markdown-it": "bin/markdown-it.mjs" } }, "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg=="],
 
+    "markdownlint": ["markdownlint@0.40.0", "", { "dependencies": { "micromark": "4.0.2", "micromark-core-commonmark": "2.0.3", "micromark-extension-directive": "4.0.0", "micromark-extension-gfm-autolink-literal": "2.1.0", "micromark-extension-gfm-footnote": "2.1.0", "micromark-extension-gfm-table": "2.1.1", "micromark-extension-math": "3.1.0", "micromark-util-types": "2.0.2", "string-width": "8.1.0" } }, "sha512-UKybllYNheWac61Ia7T6fzuQNDZimFIpCg2w6hHjgV1Qu0w1TV0LlSgryUGzM0bkKQCBhy2FDhEELB73Kb0kAg=="],
+
     "mdast-util-to-hast": ["mdast-util-to-hast@13.2.1", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/mdast": "^4.0.0", "@ungap/structured-clone": "^1.0.0", "devlop": "^1.0.0", "micromark-util-sanitize-uri": "^2.0.0", "trim-lines": "^3.0.0", "unist-util-position": "^5.0.0", "unist-util-visit": "^5.0.0", "vfile": "^6.0.0" } }, "sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA=="],
 
     "mdurl": ["mdurl@2.0.0", "", {}, "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w=="],
 
+    "micromark": ["micromark@4.0.2", "", { "dependencies": { "@types/debug": "^4.0.0", "debug": "^4.0.0", "decode-named-character-reference": "^1.0.0", "devlop": "^1.0.0", "micromark-core-commonmark": "^2.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-combine-extensions": "^2.0.0", "micromark-util-decode-numeric-character-reference": "^2.0.0", "micromark-util-encode": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-resolve-all": "^2.0.0", "micromark-util-sanitize-uri": "^2.0.0", "micromark-util-subtokenize": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA=="],
+
+    "micromark-core-commonmark": ["micromark-core-commonmark@2.0.3", "", { "dependencies": { "decode-named-character-reference": "^1.0.0", "devlop": "^1.0.0", "micromark-factory-destination": "^2.0.0", "micromark-factory-label": "^2.0.0", "micromark-factory-space": "^2.0.0", "micromark-factory-title": "^2.0.0", "micromark-factory-whitespace": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-classify-character": "^2.0.0", "micromark-util-html-tag-name": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-resolve-all": "^2.0.0", "micromark-util-subtokenize": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg=="],
+
+    "micromark-extension-directive": ["micromark-extension-directive@4.0.0", "", { "dependencies": { "devlop": "^1.0.0", "micromark-factory-space": "^2.0.0", "micromark-factory-whitespace": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0", "parse-entities": "^4.0.0" } }, "sha512-/C2nqVmXXmiseSSuCdItCMho7ybwwop6RrrRPk0KbOHW21JKoCldC+8rFOaundDoRBUWBnJJcxeA/Kvi34WQXg=="],
+
+    "micromark-extension-gfm-autolink-literal": ["micromark-extension-gfm-autolink-literal@2.1.0", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-sanitize-uri": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw=="],
+
+    "micromark-extension-gfm-footnote": ["micromark-extension-gfm-footnote@2.1.0", "", { "dependencies": { "devlop": "^1.0.0", "micromark-core-commonmark": "^2.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-sanitize-uri": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw=="],
+
+    "micromark-extension-gfm-table": ["micromark-extension-gfm-table@2.1.1", "", { "dependencies": { "devlop": "^1.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg=="],
+
+    "micromark-extension-math": ["micromark-extension-math@3.1.0", "", { "dependencies": { "@types/katex": "^0.16.0", "devlop": "^1.0.0", "katex": "^0.16.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-lvEqd+fHjATVs+2v/8kg9i5Q0AP2k85H0WUOwpIVvUML8BapsMvh1XAogmQjOCsLpoKRCVQqEkQBB3NhVBcsOg=="],
+
+    "micromark-factory-destination": ["micromark-factory-destination@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA=="],
+
+    "micromark-factory-label": ["micromark-factory-label@2.0.1", "", { "dependencies": { "devlop": "^1.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg=="],
+
+    "micromark-factory-space": ["micromark-factory-space@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg=="],
+
+    "micromark-factory-title": ["micromark-factory-title@2.0.1", "", { "dependencies": { "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw=="],
+
+    "micromark-factory-whitespace": ["micromark-factory-whitespace@2.0.1", "", { "dependencies": { "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ=="],
+
     "micromark-util-character": ["micromark-util-character@2.1.1", "", { "dependencies": { "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q=="],
 
+    "micromark-util-chunked": ["micromark-util-chunked@2.0.1", "", { "dependencies": { "micromark-util-symbol": "^2.0.0" } }, "sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA=="],
+
+    "micromark-util-classify-character": ["micromark-util-classify-character@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q=="],
+
+    "micromark-util-combine-extensions": ["micromark-util-combine-extensions@2.0.1", "", { "dependencies": { "micromark-util-chunked": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg=="],
+
+    "micromark-util-decode-numeric-character-reference": ["micromark-util-decode-numeric-character-reference@2.0.2", "", { "dependencies": { "micromark-util-symbol": "^2.0.0" } }, "sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw=="],
+
     "micromark-util-encode": ["micromark-util-encode@2.0.1", "", {}, "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw=="],
 
+    "micromark-util-html-tag-name": ["micromark-util-html-tag-name@2.0.1", "", {}, "sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA=="],
+
+    "micromark-util-normalize-identifier": ["micromark-util-normalize-identifier@2.0.1", "", { "dependencies": { "micromark-util-symbol": "^2.0.0" } }, "sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q=="],
+
+    "micromark-util-resolve-all": ["micromark-util-resolve-all@2.0.1", "", { "dependencies": { "micromark-util-types": "^2.0.0" } }, "sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg=="],
+
     "micromark-util-sanitize-uri": ["micromark-util-sanitize-uri@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-encode": "^2.0.0", "micromark-util-symbol": "^2.0.0" } }, "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ=="],
 
+    "micromark-util-subtokenize": ["micromark-util-subtokenize@2.1.0", "", { "dependencies": { "devlop": "^1.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA=="],
+
     "micromark-util-symbol": ["micromark-util-symbol@2.0.1", "", {}, "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q=="],
 
     "micromark-util-types": ["micromark-util-types@2.0.2", "", {}, "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA=="],
 
+    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
+
     "oniguruma-parser": ["oniguruma-parser@0.12.1", "", {}, "sha512-8Unqkvk1RYc6yq2WBYRj4hdnsAxVze8i7iPfQr8e4uSP3tRv0rpZcbGUDvxfQQcdwHt/e9PrMvGCsa8OqG9X3w=="],
 
     "oniguruma-to-es": ["oniguruma-to-es@4.3.4", "", { "dependencies": { "oniguruma-parser": "^0.12.1", "regex": "^6.0.1", "regex-recursion": "^6.0.2" } }, "sha512-3VhUGN3w2eYxnTzHn+ikMI+fp/96KoRSVK9/kMTcFqj1NRDh2IhQCKvYxDnWePKRXY/AqH+Fuiyb7VHSzBjHfA=="],
 
+    "parse-entities": ["parse-entities@4.0.2", "", { "dependencies": { "@types/unist": "^2.0.0", "character-entities-legacy": "^3.0.0", "character-reference-invalid": "^2.0.0", "decode-named-character-reference": "^1.0.0", "is-alphanumerical": "^2.0.0", "is-decimal": "^2.0.0", "is-hexadecimal": "^2.0.0" } }, "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw=="],
+
     "picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
 
     "playwright": ["playwright@1.58.2", "", { "dependencies": { "playwright-core": "1.58.2" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A=="],
@@ -142,8 +219,12 @@
 
     "sprintf-js": ["sprintf-js@1.0.3", "", {}, "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g=="],
 
+    "string-width": ["string-width@8.1.0", "", { "dependencies": { "get-east-asian-width": "^1.3.0", "strip-ansi": "^7.1.0" } }, "sha512-Kxl3KJGb/gxkaUMOjRsQ8IrXiGW75O4E3RPjFIINOVH8AMl2SQ/yWdTzWwF3FevIX9LcMAjJW+GRwAlAbTSXdg=="],
+
     "stringify-entities": ["stringify-entities@4.0.4", "", { "dependencies": { "character-entities-html4": "^2.0.0", "character-entities-legacy": "^3.0.0" } }, "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg=="],
 
+    "strip-ansi": ["strip-ansi@7.1.2", "", { "dependencies": { "ansi-regex": "^6.0.1" } }, "sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA=="],
+
     "strip-bom-string": ["strip-bom-string@1.0.0", "", {}, "sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g=="],
 
     "trim-lines": ["trim-lines@3.0.1", "", {}, "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg=="],
@@ -169,5 +250,7 @@
     "zwitch": ["zwitch@2.0.4", "", {}, "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A=="],
 
     "js-yaml/argparse": ["argparse@1.0.10", "", { "dependencies": { "sprintf-js": "~1.0.2" } }, "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg=="],
+
+    "parse-entities/@types/unist": ["@types/unist@2.0.11", "", {}, "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA=="],
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limcpf/everything-is-a-markdown",
-  "version": "0.5.5",
+  "version": "0.6.1",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -21,6 +21,7 @@
     "build": "bun run src/cli.ts build",
     "dev": "bun run src/cli.ts dev",
     "clean": "bun run src/cli.ts clean",
+    "lint:md:publish": "bun run scripts/lint-published-markdown.ts",
     "test:e2e": "playwright test",
     "test:e2e:focus-trap": "playwright test tests/e2e/mobile-sidebar-focus-trap.spec.ts"
   },
@@ -35,6 +36,7 @@
     "@playwright/test": "^1.58.2",
     "@types/markdown-it": "^14.1.2",
     "@types/picomatch": "^4.0.2",
-    "bun-types": "^1.3.8"
+    "bun-types": "^1.3.8",
+    "markdownlint": "^0.40.0"
   }
 }

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;