Add documentation for using Milkdown with various frameworks

- Created a new document for using components in Milkdown. - Added a guide for using plugins in Milkdown, including toggling plugins programmatically and listing official plugins. - Introduced a recipe for integrating Milkdown with Angular, including installation steps and component creation. - Added a recipe for using Milkdown with Next.js, detailing installation and component setup. - Created a guide for integrating Milkdown with NuxtJS, including installation and component creation. - Added a comprehensive guide for using Milkdown with React, covering both Crepe and core Milkdown usage. - Introduced a recipe for SolidJS integration with Milkdown, including installation and component creation. - Added a guide for using Milkdown with Svelte, detailing installation and component setup. - Created a comprehensive guide for integrating Milkdown with Vue, covering both Crepe and core Milkdown usage. - Added a recipe for using Milkdown with Vue2, including installation and component creation.
2026-01-17 14:18:08 +08:00
parent 4de3dfdd8d
commit d9ab341223
381 changed files with 125356 additions and 0 deletions
@@ -0,0 +1,142 @@
+# Announcing Telemetry Inspector
+
+There's a lot of questions from community asking that how can they know what plugins are enabled.
+From Milkdown@7.2, we've added telemetries for milkdown, it can be available by inspectors.
+
+With this API, you can inspect editor inner status.
+You can even use visualizer to visualize the data. We create a simple example on [our playground](/playground).
+
+![Milkdown Inspector](/blogs/announcing-telemetry-inspector/milkdown-inspector.gif)
+
+## Get Started
+
+Inspector will be a top-level API in Milkdown. You can use it like this:
+
+```ts
+import { Editor } from "@milkdown/core";
+import { Telemetry } from "@milkdown/ctx";
+
+const editor = await Editor.make()
+  // Inspector is disabled by default considering performance. You need to enable it manually.
+  .enableInspector()
+  // ...
+  .create();
+
+const telemetry: Telemetry[] = editor.inspect();
+```
+
+The `Telemetry` interface will have the following fields:
+
+```ts
+interface Telemetry {
+  // User defined information for the plugin.
+  metadata: Meta;
+
+  // The slices and their current value defined by the plugin.
+  injectedSlices: { name: string; value: unknown }[];
+
+  // The slices and their current value consumed by the plugin.
+  consumedSlices: { name: string; value: unknown }[];
+
+  // The timers and their duration defined by the plugin.
+  recordedTimers: { name: string; duration: number; status: TimerStatus }[];
+
+  // The timers and their duration consumed by the plugin.
+  // Generally, the plugin will wait for them.
+  waitTimers: { name: string; duration: number; status: TimerStatus }[];
+}
+
+type TimerStatus = "pending" | "resolved" | "rejected";
+
+interface Meta {
+  displayName: string;
+  description?: string;
+  package: string;
+  group?: string;
+  additional?: Record<string, any>;
+}
+```
+
+For every plugin, it'll have a telemetry if it has metadata declared.
+With the data, you'll know the sequence of the plugins loaded, the slices and timers they defined and consumed.
+For example:
+
+```ts
+[
+  {
+    metadata: {
+      displayName: "Config",
+      package: "@milkdown/core",
+      group: "System",
+    },
+    injectedSlices: [],
+    consumedSlices: [
+      /* ... */
+    ],
+    recordedTimers: [
+      {
+        name: "ConfigReady",
+        duration: 3,
+        status: "resolved",
+      },
+    ],
+    waitTimers: [],
+  },
+  {
+    metadata: {
+      displayName: "Init",
+      package: "@milkdown/core",
+      group: "System",
+    },
+    injectedSlices: [],
+    consumedSlices: [
+      /* ... */
+    ],
+    recordedTimers: [
+      {
+        name: "InitReady",
+        duration: 5,
+        status: "resolved",
+      },
+    ],
+    waitTimers: [
+      {
+        name: "ConfigReady",
+        duration: 5,
+        status: "resolved",
+      },
+    ],
+  },
+];
+```
+
+From above information, we can know that the `Init` plugin wait for `Config` plugin to be ready.
+We can build a sequence diagram from the data.
+
+![Timer Sequence](/blogs/announcing-telemetry-inspector/timer-sequence.gif)
+
+## Add Metadata for Plugin
+
+For plugin maintainers, you can add metadata to your plugin to make it more friendly to the inspector.
+
+```ts
+import { MilkdownPlugin } from "@milkdown/ctx";
+
+const yourMilkdownPlugin: MilkdownPlugin = () => {
+  /* your implementation */
+};
+
+yourMilkdownPlugin.metadata = {
+  displayName: "Your Plugin",
+  package: "your-plugin-package",
+  description: "Your plugin description",
+  group: "If you have a lot of plugins in your package, you can group them.",
+  addtitional: {
+    /* You can add any additional information here. */
+    version: "1.0.0",
+    authror: "Mike",
+  },
+};
+```
+
+With metadata, your plugin will report telemetry correctly to the inspector.