@docfuse/plugins 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Docfuse Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @docfuse/plugins
+
+English | [简体中文](./README.zh-CN.md)
+
+`@docfuse/plugins` contains the official Markdown plugins and search providers for Docfuse. All factories share one package version; normal site configuration imports them from the package root.
+
+## Install for a Docfuse site
+
+Install the package as a development dependency:
+
+```bash
+pnpm add -D @docfuse/plugins
+```
+
+`mermaid` and `pagefind` are optional peers. Install either one only when its capability is enabled:
+
+```bash
+pnpm add -D mermaid pagefind
+```
+
+```ts
+import { externalLinks, math, mermaid, pagefind } from '@docfuse/plugins'
+import { defineConfig } from 'docfuse'
+
+export default defineConfig({
+  search: { provider: pagefind() },
+  markdown: {
+    plugins: [math(), mermaid(), externalLinks()]
+  }
+})
+```
+
+## Available factories
+
+| Factory | Contract | Purpose |
+|---|---|---|
+| `externalLinks(options?)` | Markdown plugin | Adds safe attributes to external HTTP(S) links |
+| `readingTime(options?)` | Markdown plugin | Adds localized reading time |
+| `linkCard(options?)` | Markdown plugin | Converts a standalone link into a link card |
+| `kroki(options?)` | Markdown plugin | Renders Graphviz, D2, and other Kroki languages |
+| `math(options?)` | Markdown plugin | Renders formulas with remark-math and KaTeX |
+| `mermaid(options?)` | Markdown plugin | Renders Mermaid fences in the browser |
+| `plantUml(options?)` | Markdown plugin | Renders PlantUML when a trusted server is configured |
+| `pagefind(options?)` | Search provider | Builds a Pagefind index from final static HTML |
+
+When using the plugins directly with `@docfuse/markdown` in a React application, install them as regular application dependencies. A React host that enables `math()` must also import `@docfuse/plugins/math.css`.
+
+Package-root and focused factory entries such as `@docfuse/plugins/math` are public. Browser and CSS entries are consumed by generated sites and should not be treated as plugin factories.
+
+See the [official plugin guide](https://docfuse.dev/en/guide/site/plugins/) for options, examples, lifecycle differences, and verification steps.
+
+License: MIT

package/README.zh-CN.md

@@ -0,0 +1,52 @@
+# @docfuse/plugins
+
+[English](./README.md) | 简体中文
+
+`@docfuse/plugins` 提供 Docfuse 官方维护的 Markdown 插件和搜索 Provider。所有工厂共用一个包版本，常规站点配置从包根导入。
+
+## 在 Docfuse 站点中安装
+
+把插件包安装为开发依赖：
+
+```bash
+pnpm add -D @docfuse/plugins
+```
+
+`mermaid` 和 `pagefind` 是可选 Peer，只在启用对应能力时安装：
+
+```bash
+pnpm add -D mermaid pagefind
+```
+
+```ts
+import { externalLinks, math, mermaid, pagefind } from '@docfuse/plugins'
+import { defineConfig } from 'docfuse'
+
+export default defineConfig({
+  search: { provider: pagefind() },
+  markdown: {
+    plugins: [math(), mermaid(), externalLinks()]
+  }
+})
+```
+
+## 可用工厂
+
+| 工厂 | 契约 | 作用 |
+|---|---|---|
+| `externalLinks(options?)` | Markdown 插件 | 为站外 HTTP(S) 链接添加安全属性 |
+| `readingTime(options?)` | Markdown 插件 | 添加本地化阅读时长 |
+| `linkCard(options?)` | Markdown 插件 | 把独占段落的链接转换为链接卡片 |
+| `kroki(options?)` | Markdown 插件 | 渲染 Graphviz、D2 和其他 Kroki 图表 |
+| `math(options?)` | Markdown 插件 | 使用 remark-math 和 KaTeX 渲染公式 |
+| `mermaid(options?)` | Markdown 插件 | 在浏览器中渲染 Mermaid 围栏 |
+| `plantUml(options?)` | Markdown 插件 | 配置可信服务后渲染 PlantUML |
+| `pagefind(options?)` | Search Provider | 根据最终静态 HTML 生成 Pagefind 索引 |
+
+在 React 应用中直接配合 `@docfuse/markdown` 使用时，应把插件安装为普通应用依赖。启用 `math()` 的 React 宿主还需要导入 `@docfuse/plugins/math.css`。
+
+包根入口和 `@docfuse/plugins/math` 等工厂子路径属于公共 API。浏览器与 CSS 入口由生成站点消费，不是插件工厂。
+
+选项、完整示例、生命周期区别和验证方法见[官方插件指南](https://docfuse.dev/guide/site/plugins/)。
+
+许可证：MIT

package/dist/client/kroki.js

@@ -0,0 +1,221 @@
+// src/client/shared.ts
+var ICONS = {
+  copy: '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="9" y="9" width="11" height="11" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>',
+  check: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="m5 12 4 4L19 6"/></svg>',
+  source: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="m6 8-4 4 4 4M18 8l4 4-4 4M14.5 4l-5 16"/></svg>',
+  expand: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M15 3h6v6M9 21H3v-6M21 3l-7 7M3 21l7-7"/></svg>',
+  "zoom-out": '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M5 12h14"/></svg>',
+  "zoom-reset": '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M3 12a9 9 0 1 0 3-6.7L3 8"/><path d="M3 3v5h5"/></svg>',
+  "zoom-in": '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg>'
+};
+var DIAGRAM_SCALE_MIN = 0.5;
+var DIAGRAM_SCALE_MAX = 2;
+var DIAGRAM_SCALE_STEP = 0.25;
+async function copyText(value) {
+  if (navigator.clipboard) {
+    try {
+      await navigator.clipboard.writeText(value);
+      return true;
+    } catch {
+    }
+  }
+  if (typeof document.execCommand !== "function") return false;
+  const textarea = document.createElement("textarea");
+  textarea.value = value;
+  textarea.setAttribute("readonly", "");
+  textarea.style.position = "fixed";
+  textarea.style.opacity = "0";
+  document.body.append(textarea);
+  textarea.select();
+  try {
+    return document.execCommand("copy");
+  } finally {
+    textarea.remove();
+  }
+}
+function setupActions(figure) {
+  const controller = new AbortController();
+  const copyTimers = /* @__PURE__ */ new Map();
+  const dialogs = /* @__PURE__ */ new Set();
+  const source = figure.dataset.dfSource ?? "";
+  const preview = figure.querySelector(".df-diagram-preview");
+  const sourcePanel = figure.querySelector(".df-diagram-source");
+  const zoomControls = figure.querySelector(".df-diagram-zoom-controls");
+  const buttons = figure.querySelectorAll("[data-df-diagram-action]");
+  const previewHidden = preview?.hidden;
+  const sourcePanelHidden = sourcePanel?.hidden;
+  const zoomControlsHidden = zoomControls?.hidden;
+  const previewZoomWidth = preview?.style.getPropertyValue("--df-diagram-zoom-width") ?? "";
+  const previewZoomMaxWidth = preview?.style.getPropertyValue("--df-diagram-zoom-max-width") ?? "";
+  const previewScale = preview?.getAttribute("data-df-scale");
+  let scale = 1;
+  const buttonStates = [...buttons].map((button) => ({
+    button,
+    innerHTML: button.innerHTML,
+    ariaLabel: button.getAttribute("aria-label"),
+    copied: button.getAttribute("data-copied"),
+    actionError: button.getAttribute("data-df-action-error"),
+    disabled: button.disabled
+  }));
+  const updateScale = () => {
+    if (!preview) return;
+    preview.style.setProperty("--df-diagram-zoom-width", `${scale * 100}%`);
+    preview.style.setProperty("--df-diagram-zoom-max-width", `${56.25 * scale}rem`);
+    preview.dataset.dfScale = String(scale);
+    for (const button of buttons) {
+      const action = button.dataset.dfDiagramAction;
+      if (action === "zoom-out") button.disabled = scale <= DIAGRAM_SCALE_MIN;
+      if (action === "zoom-in") button.disabled = scale >= DIAGRAM_SCALE_MAX;
+      if (action === "zoom-reset") button.disabled = scale === 1;
+    }
+  };
+  if (zoomControls) updateScale();
+  for (const button of buttons) {
+    const action = button.dataset.dfDiagramAction;
+    button.innerHTML = ICONS[action] ?? "";
+    button.addEventListener(
+      "click",
+      async () => {
+        try {
+          if (action === "copy") {
+            if (!await copyText(source)) throw new Error("Copy command failed");
+            button.innerHTML = ICONS.check;
+            button.dataset.copied = "true";
+            const activeTimer = copyTimers.get(button);
+            if (activeTimer !== void 0) window.clearTimeout(activeTimer);
+            const timer = window.setTimeout(() => {
+              if (copyTimers.get(button) !== timer) return;
+              copyTimers.delete(button);
+              button.innerHTML = ICONS.copy;
+              delete button.dataset.copied;
+            }, 1500);
+            copyTimers.set(button, timer);
+          } else if (action === "source" && preview && sourcePanel) {
+            const showingSource = !sourcePanel.hidden;
+            sourcePanel.hidden = showingSource;
+            preview.hidden = !showingSource;
+            if (zoomControls) zoomControls.hidden = !showingSource;
+            button.setAttribute(
+              "aria-label",
+              showingSource ? buttonStates.find((state) => state.button === button)?.ariaLabel ?? "Show source" : button.dataset.dfDiagramPreviewLabel ?? "Show preview"
+            );
+          } else if (action === "expand" && preview) {
+            const dialog = document.createElement("dialog");
+            dialogs.add(dialog);
+            dialog.className = "df-diagram-dialog";
+            const close = document.createElement("button");
+            close.type = "button";
+            close.className = "df-diagram-dialog-close";
+            close.setAttribute("aria-label", button.dataset.dfDiagramCloseLabel ?? "Close expanded diagram");
+            close.textContent = "\xD7";
+            close.addEventListener("click", () => dialog.close(), { signal: controller.signal });
+            const expandedPreview = preview.cloneNode(true);
+            expandedPreview.style.removeProperty("--df-diagram-zoom-width");
+            expandedPreview.style.removeProperty("--df-diagram-zoom-max-width");
+            delete expandedPreview.dataset.dfScale;
+            dialog.append(close, expandedPreview);
+            dialog.addEventListener(
+              "close",
+              () => {
+                dialogs.delete(dialog);
+                dialog.remove();
+              },
+              { signal: controller.signal }
+            );
+            document.body.append(dialog);
+            dialog.showModal();
+          } else if (action === "zoom-out") {
+            scale = Math.max(DIAGRAM_SCALE_MIN, scale - DIAGRAM_SCALE_STEP);
+            updateScale();
+          } else if (action === "zoom-reset") {
+            scale = 1;
+            updateScale();
+          } else if (action === "zoom-in") {
+            scale = Math.min(DIAGRAM_SCALE_MAX, scale + DIAGRAM_SCALE_STEP);
+            updateScale();
+          }
+        } catch (error) {
+          button.dataset.dfActionError = "true";
+          console.error("[docfuse] Diagram action failed:", error);
+        }
+      },
+      { signal: controller.signal }
+    );
+  }
+  return () => {
+    controller.abort();
+    copyTimers.forEach((timer) => window.clearTimeout(timer));
+    dialogs.forEach((dialog) => dialog.remove());
+    copyTimers.clear();
+    dialogs.clear();
+    if (preview && previewHidden !== void 0) preview.hidden = previewHidden;
+    if (sourcePanel && sourcePanelHidden !== void 0) sourcePanel.hidden = sourcePanelHidden;
+    if (zoomControls && zoomControlsHidden !== void 0) zoomControls.hidden = zoomControlsHidden;
+    if (preview) {
+      if (previewZoomWidth) preview.style.setProperty("--df-diagram-zoom-width", previewZoomWidth);
+      else preview.style.removeProperty("--df-diagram-zoom-width");
+      if (previewZoomMaxWidth) preview.style.setProperty("--df-diagram-zoom-max-width", previewZoomMaxWidth);
+      else preview.style.removeProperty("--df-diagram-zoom-max-width");
+      if (previewScale == null) preview.removeAttribute("data-df-scale");
+      else preview.setAttribute("data-df-scale", previewScale);
+    }
+    buttonStates.forEach(({ button, innerHTML, ariaLabel, copied, actionError, disabled }) => {
+      button.innerHTML = innerHTML;
+      button.disabled = disabled;
+      if (ariaLabel === null) button.removeAttribute("aria-label");
+      else button.setAttribute("aria-label", ariaLabel);
+      if (copied === null) button.removeAttribute("data-copied");
+      else button.setAttribute("data-copied", copied);
+      if (actionError === null) button.removeAttribute("data-df-action-error");
+      else button.setAttribute("data-df-action-error", actionError);
+    });
+  };
+}
+function enhanceDiagrams(root, kind, render) {
+  let active = true;
+  let disposed = false;
+  const figures = Array.from(root.querySelectorAll(`[data-df-plugin-diagram="${kind}"]`)).filter(
+    (figure) => figure.dataset.dfEnhanced !== "true"
+  );
+  const renderErrorStates = figures.map(
+    (figure) => [figure, figure.getAttribute("data-df-render-error")]
+  );
+  const cleanups = [];
+  const renders = [];
+  for (const figure of figures) {
+    figure.dataset.dfEnhanced = "true";
+    cleanups.push(setupActions(figure));
+    if (render) {
+      renders.push(
+        render(figure).catch((error) => {
+          if (!active) return;
+          figure.dataset.dfRenderError = "true";
+          console.error(`[docfuse] ${kind} render failed:`, error);
+        })
+      );
+    }
+  }
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    active = false;
+    cleanups.reverse().forEach((cleanup) => cleanup());
+    renderErrorStates.forEach(([figure, renderError]) => {
+      delete figure.dataset.dfEnhanced;
+      if (renderError === null) figure.removeAttribute("data-df-render-error");
+      else figure.setAttribute("data-df-render-error", renderError);
+    });
+  };
+  return Object.assign(dispose, {
+    ready: Promise.all(renders).then(() => void 0),
+    dispose
+  });
+}
+
+// src/client/kroki.ts
+function enhance(root = document) {
+  return enhanceDiagrams(root, "kroki");
+}
+export {
+  enhance
+};