Zurück zur Plugin-Galerie Entwickler-Leitfaden

Ein Marknote-Plugin bauen

Ein Plugin ist ein Ordner mit einem manifest.json und einem JS-Einstiegspunkt. Marknote lädt sie in eine abgeschottete WebView2 beim Start; von dort aus kann ein Plugin Befehle für die Palette und Umwandlungen der Vorschau registrieren. Die API ist mit Absicht klein – was hier steht, ist das, was 1.4.0 mitbringt. Mehr kommt in späteren Versionen.

Wo Plugins liegen

Unter Windows legen Sie den Ordner Ihres Plugins hierhin:

%LocalAppData%\Marknote\plugins\<your-plugin-id>\
  manifest.json
  main.js

Open Einstellungen → Plugins in Marknote, um zu sehen, was gefunden wurde. Manifeste, die durchfallen, erscheinen mit einer Statuszeile, die genau sagt, welches Feld falsch ist. Wenn Sie neue Dateien in den Ordner gelegt haben, klicken Sie auf Reload , um erneut zu suchen, ohne die App neu zu starten – die Laufzeit aktiviert Plugins aber nur beim Start, ein frisch abgelegtes Plugin läuft also erst nach einem Neustart.

manifest.json

Ein Pflichtobjekt je Plugin. Das Schema unten ist der vollständige Satz an Feldern, die Marknote 1.4 versteht.

{
  "id": "uk.marknote.demo",
  "name": "Marknote Demo",
  "version": "1.0.0",
  "author": "Gregory Hulsmann",
  "description": "Reference plugin demonstrating commands and previewTransforms.",
  "main": "main.js",
  "homepage": "https://marknote.md/plugins",
  "contributes": ["commands", "previewTransforms"],
  "minMarknoteVersion": "1.4.0"
}

Field	Required	Notes
`id`	Ja	Im Reverse-DNS-Stil. Wird zum Ordnernamen UND zur Identität, der jede Registrierung zugerechnet wird. Ein Umbenennen nach der Veröffentlichung zerbricht jede Installation.
`name`	Ja	Der Name, der unter Einstellungen → Plugins angezeigt wird.
`version`	Ja	Semver, ohne führendes „v“. Wird mit jeder Veröffentlichung Ihres Plugins erhöht.
`main`	Ja	Pfad zu Ihrer JS-Einstiegsdatei, relativ zum Plugin-Ordner. Muss ein einzelner Abschnitt mit der Endung .js sein.
`author`	—	Erscheint unter Einstellungen → Plugins als Zeile mit der Urheberschaft.
`description`	—	Eine Zusammenfassung in einer Zeile, unter dem Namen des Plugins.
`homepage`	—	Anklickbar unter Einstellungen → Plugins. Verweisen Sie auf die Dokumentation oder Ihren Issue-Tracker.
`contributes`	—	Die angemeldeten Fähigkeiten. Eine anzugeben, die Sie nicht nutzen, schadet nicht; eine API für eine nicht angemeldete Fähigkeit aufzurufen, wirft zur Laufzeit einen Fehler. Bekannte Werte: "commands", "previewTransforms".
`minMarknoteVersion`	—	Das Plugin wird mit einer klaren Fehlermeldung übersprungen, wenn die laufende App älter ist.

Die marknote-API

Die main.js Ihres Plugins wird in einem IIFE ausgewertet, das ein marknote -Objekt erhält, das auf Ihre Plugin-id begrenzt ist. In 1.4.0 sind drei Flächen offen:

`marknote.commands.register({ id, title, run })`

Fügt der Befehlspalette von Marknote einen Befehl hinzu (Ctrl+Shift+P). Befehle erscheinen unten in der Palette, mit dem Präfix Plugin · . Wählt jemand einen aus, wird Ihr run -Rückruf ausgelöst.

marknote.commands.register({
  id: 'show-timestamp',
  title: 'Show timestamp',
  run() {
    marknote.notify('Plugin clock: ' + new Date().toLocaleString());
  },
});

`marknote.preview.onTransform(fn)`

Registriert eine Umwandlung von Markdown zu Markdown. Die Funktion läuft bei jedem Rendern auf dem Markdown-Quelltext, bevor markdig ihn sieht. Ein rein synchroner Rückgabewert funktioniert; ein zurückgegebenes Promise<string> funktioniert ebenfalls. Je Umwandlung gilt eine Grenze von 4 Sekunden – wird sie überschritten, nimmt Marknote den Inhalt vor der Umwandlung, statt die Vorschau einfrieren zu lassen.

marknote.preview.onTransform(function (markdown) {
  const today = new Date().toISOString().slice(0, 10);
  return markdown.split('{{date}}').join(today);
});

`marknote.notify(text)`

Zeigt eine kurze Meldung in der Statusleiste von Marknote. Nützlich für Befehls-Rückrufe, die eine Aktion bestätigen wollen, ohne einen Dialog zu öffnen. Nur Zeichenketten.

Referenz-Plugin

Das öffentliche wearemarknote/plugins -Repository enthält ein lauffähiges Beispiel unter marknote-demo/ – ein Manifest und eine main.js aus 20 Zeilen, die beide Beiträge zeigt. Kopieren Sie den Ordner nach %LocalAppData%\Marknote\plugins\ und starten Sie die App neu, um es auszuprobieren. Quelle: github.com/wearemarknote/plugins.

Das Sandbox-Modell

Jedes Plugin läuft in einer gemeinsamen WebView2 ohne DOM-Mittel (kein fetch, kein XHR dank CSP, keine Entwicklerwerkzeuge, kein Kontextmenü). Plugin-Code steckt in einem IIFE, damit var / let -Deklarationen nicht zwischen Plugins überlaufen. Die Brücke zu .NET ist der einzige Kanal für Nebenwirkungen – jede Registrierung, jedes Ergebnis einer Umwandlung und jede Meldung reist über einen verfolgten WebMessage-Umlauf.

Dies ist noch keine Sandbox gegen Angreifer – ein bösartiges Plugin kann weiterhin in einer Endlosschleife laufen oder die CPU belegen. Installieren Sie keine Plugins aus Quellen, denen Sie nicht trauen. Eine härtere Sandbox (Origin-Isolation, ein iframe je Plugin, Zeitscheiben) steht auf der Roadmap.

Was als Nächstes kommt

Zwei Bereiche, an denen für die nächsten Versionen gearbeitet wird:

Marketplace – Stöbern in der App und Installieren mit einem Klick, mit einem moderierten Katalog.
Größere API – Zugriff auf den Editor (Cursor lesen, an der Auswahl einfügen), Abfragen des Arbeitsbereichs (Notizen auflisten, eine Datei lesen), Registrieren von Exportern. Getrieben davon, was Plugin-Schreibende wirklich brauchen; melden Sie ein Issue, wenn Sie feststecken.

Etwas gebaut?

Öffnen Sie einen PR oder ein Issue auf github.com/wearemarknote/issues mit einem Link auf Ihr Repository und einer Beschreibung in einer Zeile. Nach der Freigabe kommt es in die Plugin-Galerie.