Machen wir uns nichts vor: Ich versuche, meine Plugins so zu gestalten, dass sie möglichst einfach einzurichten sind, aber umfangreiche Plugins, wie beispielsweise der IndieConnector, haben so viele Anpassungsmöglichkeiten, dass man schon mal den Überblick verlieren kann.

Deshalb habe ich ein kleines Tool gebaut, welches alle Optionen des Plugins als Tabelle ausgeben kann (so wie sie bisher bei meinen Plugins zu finden war). Das Tool kann aber aus diesen Daten auch einen Wizard machen.

Ich habe beim IndieConnector damit begonnen. Dort kannst Du nun den Konfigurationsassistenten aufrufen und wirst Schritt für Schritt durch die wichtigsten Konfigurationen geleitet. Wähle aus, welches Feature du nutzen willst, und konfiguriere dieses dann direkt hier auf der Seite.

Am Ende des Assistenten bekommst du eine fertige Konfiguration angezeigt, die Du genauso in Deine config.php kopieren kannst.

Ich beschränke mich hier auf die wichtigsten Funktionen und Optionen. Du kannst bei Bedarf also noch in die Doku gucken, um Dein Setup noch weiter zu individualisieren. Aber mit dem Assistenten hast Du dann bereits ein solides Setup.

Das Ganze ist mit einer ersten Version gestartet und ich bin gespannt, wie es genutzt wird und was ich daran noch verbessern kann. Hier findest Du den Assistenten für den IndieConnector (weitere Plugins werden folgen):

In diesem Kurs lernst Du nicht nur, wie Kirby funktioniert, nach Abschluss hast du zudem ein funktionierendes Blog mit Anbindung an Mastodon und Bluesky.

Kursumfang

In diesem Kurs bauen wir gemeinsam ein Blog mit Kirby. Dabei lernen wir alle Grundlagen und zahlreiche erweiterte Funktionen, um nach Abschluss des Kurses live gehen zu können. Mit dem erlernten Wissen wirst Du in der Lage sein, Dein Blog weiter anzupassen und eigene, neue Features zu entwickeln.

Unser Blog kommt mit allen Standards daher: einem gruppierten Bloglisting, Filter für Tags, einem Listing für Kategorien, Kommentaren, einem RSS-Feed, Open-Graph-Daten und automatisch erzeugten Vorschaubildern zum Teilen bei Mastodon und Bluesky.

Wir installieren das IndieConnector-Plugin, um automatisch bei Mastodon und Bluesky zu posten und Antworten zurück ins Blog zu holen.

Wir erstellen eine Blogroll, eine Sitemap und eine robots.txt. Wir werden Beiträge planen und automatisch veröffentlichen können. Alle geplanten Beiträge können wir als Kalender abonnieren.

Wir entwickeln das Blog lokal und lernen, wie wir Kirby installieren und aktualisieren, wie Plugins installiert werden und wie wir schließlich unser Blog online bekommen.

Du lernst

• Installation via composer
• Konfiguration des Systems
• Templates und Blueprints
• Snippets
• Controller und deren Vererbung
• Panel-Anpassungen
• Panel-Felder
• Panel Blueprint-Querys
• Kirby Helper-Methoden
• Filter und Gruppierungen
• Paginierung und Breadcrumbs
• Schreiben mit Markdown
• Such-Funktionen
• Entwicklung einfacher Plugins
• page- und site-methods
• Virtuelle Seiten
• uvm.

Gut zu wissen

Auch wenn wir HTML und CSS schreiben werden, ist dieser Kurs kein Frontend-Entwicklungs-Kurs, der Fokus wird auf Kirby liegen. Wir schaffen aber eine solide Grundlage, die gut aussieht und die Du weiter verfeinern kannst.

Dieser Kurs wird kostenpflichtig zu einem fairen Preis angeboten werden. Du bekommst Zugriff auf einen geschlossenen Bereich und wirst die Möglichkeit haben, Fragen zu stellen, falls Du mal nicht weiterkommen solltest. Die Umsetzung erfolgt in Text- und Videoform in englischer Sprache (mit charmant deutschem Akzent).

Wenn das für Dich interessant klingt, trage Dich jetzt unverbindlich in den Newsletter ein und Du bekommst gelegentlich Updates zum Stand der Dinge und natürlich zum offiziellen Launch des Kurses.

Wann geht es los?
Ein wenig Zeit benötige ich noch, um Kapitel abzurunden und aufzunehmen. Ein genaues Datum werde ich bald bekanntgeben.

Die Person wird mit hoher Wahrscheinlichkeit auf einer fremden Instanz landen und muss von dort erst einmal zur eigenen Instanz finden, um dort dann auf den Post reagieren zu können. Auch ein einfacher "Folgen"-Button wird so schnell zur Hürde.

Das haben auch andere erkannt und arbeiten an Lösungen, wie dem "Universal Follow Button", der vielleicht einmal kommen mag. Und während ich diesen Artikel fast fertig habe, erscheint der neue Share-Button von Mastodon, dazu später mehr.

Auf meiner Seite habe ich deshalb versucht, Dine zu vereinfachen. Leserinnen geben ihre Mastodon-Instanz ein und werden dann direkt zum passenden Post geleitet.

Zu (fast) jedem meiner Beiträge auf meiner Seite gibt es auch einen Mastodon-Post. Reaktionen auf diesen Post werden synchronisiert und unter dem Beitrag auf meiner Seite angezeigt, darum kümmert sich der [[/kirby/indieconnector|IndieConnector]].

Ich kann also automatisch auf diesen Post verweisen, würde dann aber auf das oben beschriebene Problem stoßen. User würden auf meine Instanz gelangen, nicht auf ihre, und könnten nicht direkt reagieren – suboptimal.

Statt den Post direkt zu verlinken, müssen meine Leserinnen erst einmal ihre Instanz eintragen und können sich entscheiden, ob diese Instanz (im Browser) gespeichert werden soll:

Das Formular ist schlicht aufgebaut:

<form action="/reply/mastodon" method="post">
    <input type="url" value="" name="instance" id="instance" placeholder="https://mastodon.instance" required>
    <input type="hidden" name="target" value="<?= $mastodonUrl ?>">
    <button type="submit" class="button-primary">Ok</button>

    <input type="checkbox" name="rememberInstance" id="rememberInstance" value="true">
    <label for="rememberInstance" class="remember">
        Remember
    </label>
</form>

Im Wesentlichen enthält das Formular zwei Daten:

1. Die Instanz des Users
2. Meine jeweilige Mastodon-Post-URL

Ein Klick auf den Button leitet dann zur Instanz weiter und zeigt dort meinen Post an, auf den dann direkt reagiert werden kann.

Ich löse das über eine [[/kirby|Kirby]]-Route, die Umsetzung funktioniert aber genauso gut mit einer einfachen PHP-Datei, die irgendwo aufrufbar ist.

So sieht die Route aus:

[
    'pattern' => 'reply/mastodon',
    'method' => 'POST',
    'action' => function () {
        $request = kirby()->request();
        $data = $request->data();

        if (!isset($data) || empty($data)) {
            return new Response('No POST data found', 'text/plain', 400); // Not Acceptable
        }

        $instanceUrl = Url::stripPath($data['mastodonInstance']);
        $url = $instanceUrl . '/authorize_interaction?uri=' . $data['target'];

        if ($data['rememberInstance'] == true) {
            // set cookie
            Cookie::set('mastodon_instance', $instanceUrl, [
                'lifetime' => time() + 60 * 60 * 24 * 365,
                'path' => '/',
                'httpOnly' => false,
            ]);
        }

        header::redirect($url);
    },
],

Der Code sähe ohne Kirby ähnlich aus (gekürzt):

$data = $_POST;

$parsedUrl = parse_url($data['mastodonInstance']);
$instanceUrl = $parsedUrl['scheme'] . '://' . $parsedUrl['host'];

$url = $instanceUrl . '/authorize_interaction?uri=' . $data['target'];

if (!empty($data['rememberInstance'])) {
    setcookie(
        'mastodon_instance',
        $instanceUrl,
        [
            'expires'  => time() + 60 * 60 * 24 * 365,
            'path'     => '/',
            'httponly' => false,
        ]
    );
}

header('Location: ' . $url);

Hier ist es zudem sinnvoll, zu prüfen, ob die Daten leer sind und ob es sich um einen POST-Request handelt. Da viele Leserinnen hier vermutlich ein CMS nutzen werden, habe ich mich entschlossen, diese Details wegzulassen, weil sie wahrscheinlich sowieso vom System gehandhabt werden.

Die eigentliche Magie ist in einer Zeile versteckt und ziemlich simpel:

$url = $instanceUrl . '/authorize_interaction?uri=' . $data['target'];

Wir bauen aus den gegebenen Informationen eine neue URL zusammen, beginnend mit der eingegebenen Instanz (ohne eventuellen Pfad hinten dran) dem Pfad /authorize_interaction und dem uri-Parameter, der die volle URL zu unserem Mastodon-Post enthält.

Der Endpunkt /authorize_interaction macht genau das, was man vermuten könnte: Er erlaubt die Interaktion mit, in diesem Fall, einem Post. Durchlaufen wir den Flow, sind wir also bereits auf der eigenen Instanz und haben dort dann über den Endpunkt die Möglichkeit, auf den Post zu reagieren, egal auf welcher Instanz sich dieser befindet.

Das geht übrigens auch mit User-Profilen und ist praktisch für einen "Follow-Button", wie ihn der Dienst oben anbieten will.

Unsere Leserinnen müssen also im besten Fall nur einmal ihre Instanz hinterlegen und können dann ohne weitere Umstände mit unseren Mastodon-Inhalten interagieren, denn sie gelangen immer auf ihre eigene Instanz und sehen dort den jeweiligen Post oder das Profil. Wir haben ihnen das umständliche Suchen und Copy & Paste abgenommen.

Nun gibt es seit dem 2. März einen offiziellen Share-Button von Mastodon, den man sich einfach zusammenklicken kann:

https://blog.joinmastodon.org/2026/03/a-new-share-button/

Und obwohl ich die Idee gut finde, habe ich zwei Probleme damit:

1. Er erzeugt einen neuen Beitrag
2. Er streicht die Dezentralität

In meinem speziellen Use-Case ist es so, dass der IndieConnector nur Reaktionen von Posts abholt, die im Plugin hinterlegt sind. Es besteht eine 1:1-Beziehung zwischen Blogbeitrag und Mastodon-Post. Der Share-Button erzeugt aber immer neue Beiträge. Das ist zumindest nicht das, was ich will.
Er ist aber sicherlich für all diejenigen passend, die gerne möchten, dass Leserinnen schnell und einfach Zitate oder URLs als eigene Posts teilen können. Aber!

Alles läuft über share.joinmastodon.org. Dort müssen die User dann ihre Instanz eingeben und werden dann auf diese Instanz umgeleitet, um dort unter dem share-Endpunkt einen neuen Post zu erstellen.

Wir können uns denken, was im Hintergrund passiert: vermutlich genau das, was wir im oben beschriebenen PHP-Code machen.

Das ist an sich vollkommen okay, wäre da nicht eine Sache: Es gibt eine zentrale Schnittstelle. Jeder Share-Button oder -Link läuft nun über share.joinmastodon.org. Man möge mich pingelig nennen, aber genau das wollten wir ja mit Mastodon gerne vermeiden.

Nun ist nicht jeder Entwickler oder möchte sich irgendeinen, irgendwas tuenden PHP-Code vibe coden, dafür ist das zumindest ein guter Anfang. Wer aber kann, sollte vielleicht eher den oben beschriebenen Weg gehen. Dieser hat den Charme, dass unsere eigene Webseite die "zentrale" Schnittstelle ist, und auf der befindet sich die Leserin sowieso schon. Außerdem ist der /authorize_interaction Endpunkt kein reiner Mastodon-Endpunkt, sondern Teil von ActivityPub und kann also auch außerhalb von Mastodon benutzt werden.

Ich bin gespannt, wie der Follow-Button umgesetzt werden wird. Ihr habt jetzt jedenfalls ein paar einfache Zeilen PHP-Code und einen hilfreichen Endpunkt zur Hand, mit denen ihr all das schon jetzt ohne externe Services einbauen könnt. Viel Spaß!

Ich wollte das eigentlich vermeiden, aber zu sehr aktiven Zeiten wird meine Seite dank Cache zwar zügig ausgespielt, das Kirby-Panel ist aber kaum mehr zu bedienen und endlos langsam. Maßgeblich betrifft das Anfragen aus Singapur, die ich nun leider abweisen muss.

$serverSideStories = $site->rssPages('https://konzentrik.de/server-side-stories/feed')->sortBy('date', 'desc')->limit(5);
$sociabli = $site->rssPages('https://sociab.li/blog/feed.xml')->sortBy('date', 'desc')->limit(5);

Und dann auf der Startseite mein Textlisten-Snippet benutzen:

<?php snippet('list/textlist', ['articleList' => $sociabli, 'useLink' => true]); ?>

Das war's!

In diesem Beitrag habe ich bereits erklärt, wie wir mit Kirby und Raycast eine neue Notiz anlegen und veröffentlichen können. Diesen Code nehmen wir nun als Grundlage und treiben das Ganze auf die Spitze.

Das Ziel unseres Experiments: Wir möchten uns in Signal eine Nachricht schicken und diese Nachricht soll als Notiz im Kirby-Blog online gehen. Dazu nutzen wir den bereits beschriebenen POSSE-Endpunkt.

Signal CLI

Damit wir Nachrichten abgreifen und etwas mit ihnen machen können, benötigen wir irgendwie Zugriff. Hier hilft uns das Signal-CLI-Projekt, für das es dankenswerterweise einen Wrapper gibt, der uns eine REST-API bereitstellt.

Einmal gestartet, können wir dieses Tool als neues Gerät in unserem Account registrieren. Deshalb hiermit noch einmal die Warnung: Das hier ist ein Experiment! Falsch konfiguriert, kann dieses Setup im schlimmsten Fall möglichen Angreifern Zugriff auf alle eure Nachrichten verschaffen!

Wir lassen Signal-CLI in einem Docker-Container laufen. Dazu legen wir ein docker-compose.yaml an:

services:
  signal:
    image: bbernhard/signal-cli-rest-api:latest
    container_name: signal-api
    environment:
      - MODE=native #supported modes: json-rpc, native, normal
    ports:
      - "8080:8080" #map docker port 8080 to host port 8080.
    volumes:
      - "./signal-cli-config:/home/.local/share/signal-cli"

Als Basis dient uns das Signal-CLI-Rest-Api Docker-Image. Viel müssen wir gar nicht tun, wir setzen ein paar Grundeinstellungen. Wichtig ist das Volume, hier werden die Metadaten abgelegt, wie beispielsweise der Hinterlegte Account. Das Verzeichnis sollte also unbedingt erhalten bleiben, damit wir nicht ständig ein neues Gerät hinzufügen müssen.

Mit folgendem Befehl können wir das Setup testen:

docker-compose up

Danach können wir im Browser folgende URL aufrufen:

http://localhost:8080/v1/qrcodelink?device_name=signal-api

Wir müssen unsere laufende CLI-Instanz nun zu den vertrauten Geräten hinzufügen. In der Signal App gehen wir dazu auf den eigenen Avatar und dann "Gekoppelte Geräte" → "Neues Gerät hinzufügen". Sobald wir den QR-Code im Browser gescannt haben, sind wir startklar.

Signal-CLI kann nun auf alle Nachrichten zugreifen. Damit können wir aber noch nichts anfangen. Wirbenötigenn noch eine Verknüpfung zwischen Signal-CLI und unserem POSSE-Endpunkt. Dazu schreiben wir uns ein kleines Typescript.

Das Skript

Dazu legen wir das Verzeichnis bot an und erstellen dort eine package.json, damit wir alle Abhängigkeiten parat haben:

{
  "name": "signal-bot",
  "version": "1.0.0",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "axios": "^1.6.0",
    "dotenv": "^16.3.1"
  },
  "devDependencies": {
    "typescript": "^5.4.0",
    "@types/node": "^22.0.0"
  }
}

Wie man sieht, hält sich der Umfang in Grenzen. Im nächsten Schritt legen wir eine tsconfig.json Datei an.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "types": ["node"]
  },
  "include": ["index.ts"]
}

Zuerst fangen wir damit an, die wichtigesten Eckdaten auszulesen. Wir verwenden Environment-Variablen.

import axios from "axios";

const SIGNAL_API = process.env.SIGNAL_API!;
const SIGNAL_NUMBER = process.env.SIGNAL_NUMBER!;
const TARGET_API = process.env.TARGET_API!;
const KIRBY_SECRET = process.env.KIRBY_SECRET!;

Wir benötigen den API-Endpunkt, den uns unser Docker-Container bereitstellt, unsere eigene Telefonnummer, den Kirby-POSSE-Endpunkt und das Kirby-Secret.

async function poll() {
  try {
    const res = await axios.get(
      `${SIGNAL_API}/v1/receive/${encodeURIComponent(SIGNAL_NUMBER)}`,
    );
    const messages = res.data;

    for (const msg of messages) {
      const sender = msg.envelope?.source;
      const destination =
        msg.envelope?.syncMessage?.sentMessage?.destinationNumber;
      const text =
        msg.envelope?.dataMessage?.message ||
        msg.envelope?.syncMessage?.sentMessage?.message;

      if (sender === SIGNAL_NUMBER && destination === SIGNAL_NUMBER && text) {
        console.log(`Forwarding message: ${text}`);
      }
    }
  } catch (error) {
    if (error instanceof Error) {
      console.error("Error polling messages:", error.message);
    } else {
      console.error("Unknown error:", error);
    }
  }
}

Wir beginnen damit, den Signal-Endpunkt aufzurufen. Er liefert uns eine Liste ungelesener Nachrichten zurück, die wir durchlaufen. Wir brauchen ein paar Daten, die wir uns holen:

• Die Absenderin der Nachricht
• Die Empfängerin der Nachricht
• Den Text der Nachricht

Beim Text gibt es eine kleine Besonderheit. Da wir den Text an uns selbst schicken werden (Notiz an mich), wird dieser Text sofort als gelesen markiert werden und wir finden den Text dann nicht mehr unter envelope?.dataMessage?.message wie es normalerweise der Fall wäre, sondern unter envelope?.syncMessage?.sentMessage?.message. Um ganz sicher zu sein, fragen wir beide Werte ab, ist ersterer leer, fallen wir auf die verschickten Daten zurück.

Da wir auf jede Nachricht reagieren und damit jede Nachricht in jedem Chat eine Notiz in Kirby erzeugen würde, müssen wir zunächst die passenden Nachrichten filtern:

if (sender === SIGNAL_NUMBER && destination === SIGNAL_NUMBER && text)

Diese Abfrage sorgt dafür, dass wir nur auf Nachrichten reagieren, die von unserer eigenen Nummer an unsere eigene Nummer gehen und die einen Text haben. Damit sind wir einigermaßen abgesichert.

Jetzt füllen wir den if-Block. Darin wollen wir den API-Request in Richtung Kirby absetzen:

let skipUrl = false;
let ext = false;
let autopublish = true;

// Find and remove hashtags, set flags
let parsedText = text
  .replace(/#skipUrl\b/gi, (_match: any) => {
    skipUrl = true;
    return "";
  })
  .replace(/#ext\b/gi, (_match: any) => {
    ext = true;
    return "";
  })
  .replace(/#draft\b/gi, (_match: any) => {
    autopublish = false;
    return "";
  })
  .trim();

await axios.post(
  TARGET_API,
  {
    posttext: parsedText,
    externalPost: ext,
    skipUrl,
    autopublish,
  },
  {
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${KIRBY_SECRET}`,
    },
  },
);

Zunächst setzen wir ein paar Standardwerte. Die haben wir im bereits erwähnten POSSE-Beitrag festgelegt. Sie ermöglichen es uns, Kirby zu steuern.

• skipUrl legt fest, ob beim Posten zu Mastodon ein Link zur Notiz angehangen werden soll.
• ext legt fest, ob überhaupt zu Mastodon oder Bluesky gepostet werden soll.
• autopublish legt fest, ob die Notiz sofort veröffentlicht oder als Entwurf abgelegt werden soll.

Da wir im Signal-Chat keine passenden Buttons haben, verwenden wir Hashtags: #skipUrl, #ext und #draft.

Wir suchen nach diesen Hashtags im Text, ignorieren dabei Groß- und Kleinschreibung und setzen die entsprechenden Variablen. Schließlich entfernen wir die Hashtags aus dem Text, so dass sie in der Notiz nicht mehr vorkommen.

Ich habe autopublishing aktiviert und deaktivieren es gezielt mit dem Hashtag #draft. Das lässt sich bei Bedarf natürlich auch umkehren.

Schließlich setzen wir den API-Request in Richtung Kirby ab. Wie man sieht, enthält er alle notwendigen Felder und unser Secrect im Header.

Damit sind wir fast fertig. Wir müssen unsere Methode nur noch regelmäßig aufrufen, um nach neuen Nachrichten zu schauen:

setInterval(poll, 10_000);

Docker Compose

Bevor wir fertig sind, müssen wir unser docker-compose.yml noch anpassen. Wir wollen unseren Bot zusammen mit Signal-CLI hochfahren. Dazu braucht unser Bot zunächst ein Dockerfile:

FROM node:22-alpine

WORKDIR /app
COPY . .
RUN npm install
RUN npm run build

CMD ["node", "dist/index.js"]

Wir benutzen das node-alpine Image als Grundlage, installieren alle notwendigen Pakete, bauen unser Skript und starten es.

Hier lässt sich sicherlich noch optimieren und Platz sparen, aber für unser Experiment passt das.

Nun müssen wir noch unser docker-compose.yml erweitern. Unter dem bereits vorhanden Signal-Code ergänzen wir:

services:
    signal:
        # see code above
    bot:
        build: ./bot
        container_name: signal-bot
        environment:
          - SIGNAL_API=http://signal:8080
          - SIGNAL_NUMBER=+491234567890
          - TARGET_API=https://my-blog.tld/posse
          - KIRBY_SECRET=abc-def-ghi
        depends_on:
          - signal
        restart: unless-stopped

Hier setzen wir unsere Environment-Variablen. Für den Signal-Endpunkt benutzen wir den Containernamen. Wir müssen noch unsere Telefonnummer mit Ländervorwahl angeben und natürlich unseren Kirby-POSSE-Endpunkt und -Secret.

Unser Bot wartet darauf, dass die Signal-CLI vorhanden ist und fährt erst dann hoch.

Damit unser Bot gebaut wird, müssen wir bei Code-Änderungen diesen Befehl aufrufen:

docker compose up --build

Danach langt es, docker-compose aufzurufen:

docker-compose up

Sollen die Container im Hintergrund laufen, können wir einfach -d ergänzen:

docker-compose up -d

Fertig!

Jetzt können wir eine Nachricht an uns selbst schicken:

Unser Skript greift diese Nachricht auf:

Sendet sie an Kirby und publiziert die Notiz:

Und das IndieConnector-Plugin schickt sie weiter an Mastodon, weil wir externes Posten aktiviert haben:

Jetzt können wir in alter Twitter-Manier vom Telefon aus in die eigenen Notizen posten und nach Belieben weiter verteilen.

Abschließend sei noch angemerkt, dass alle Nachrichten, die wir an uns selbst schicken, veröffentlicht werden. Wer die Notiz an mich Funktion von Signal anderweitig nutzt, sollte die Logik etwas erweitern und einen weiteren Hashtag fürs Posten einfügen. So könnte #posse den Ablauf auslösen und alle anderen Nachrichten ignoriert werden. Vielleicht eine gute Idee, um versehentliche Notizen zu vermeiden.

Es sei noch einmal erwähnt, dass es sich hier um ein Experiment handelt, das zeigen soll, was wir alles mit unseren Blogs anstellen können. Wer das Skript in der Form betreiben will, sollte sich im Klaren darüber sein, welche Sicherheitsrisiken durch den Betrieb von Signal-CLI entstehen, besonders wenn der API-Endpunkt öffentlich verfügbar gemacht wird.

Dennoch: Viel Spaß beim Ausprobieren!

Mit nur einem Tastenkürzel werden wir jederzeit Zugriff auf das Formular in Raycast haben. Es wird ausreichen, einen Texte einzugeben und das Formular abzuschicken, um im Kirby-CMS eine Notiz oder ein Lesezeichen zu erstellen und diese von Kirby aus auf andere Plattformen zu verteilen (POSSE).

Auf dem Mac werden wir dafür Raycast benutzen. Raycast erlaubt es uns, schnell Befehle auszuführen, diesen Befehlen Tastenkürzel und einen Alias zuzuweisen.

Ich möchte auf meinem Mac die Tastenkombination SUPER+N drücken, um dieses Fenster zu öffnen und eine neue Notiz zu erstellen:

Hier kann ich einen kurzen Text eingeben, wenn ich ein Lesezeichen erstellen möchte, eine URL, einen optionalen Seitentitel und schließlich kann ich noch festlegen, ob der Beitrag sofort veröffentlicht werden soll, ob er ebenfalls bei Mastodon gepostet werden soll und ob eine URL an den Post bei Mastodon gehangen werden soll.

Was benötigen wir?

• Ein Kirby-Plugin, das eine Route bereitstellt, die eine neue Notiz anlegt
• Ein Raycast-Plugin, welches eine schnelle Eingabe erlaubt und die Kirby-Route aufruft
• Das IndieConnector-Plugin, welches den POSSE-Teil übernimmt

Grundlagen

Auf meiner Webseite unterscheide ich zwischen zwei Arten von Notizen:

1. Die einfache Textnotiz
2. Ein Lesezeichen

Beide benutzen unterschiedliche Templates und verhalten sich auf der Seite unterschiedlich.

Um Beiträge automatisch bei Mastodon zu posten, verwende ich das IndieConnector-Plugin. Die Installation erfolgt in unserem Beispiel über Composer. Im Hauptverzeichnis von Kirby rufen wir auf:

composer require mauricerenck/indieconnector

Damit ist der IndieConnector installiert und kann konfiguriert werden. Dazu wechseln wir in die Datei sites/config/config.php und nehmen folgende Einstellungen vor:

'mauricerenck.indieConnector' => [
    'secret' => 'my-secret',
    'sqlitePath' => './content/.db/',
    'stats' => [
        'enabled' => true,
    ],

    'post' => [
        'prefereLanguage' => 'en',
        'allowedTemplates' => ['bookmark', 'note'],
        'textfields' => ['text'],
    ],

    'mastodon' => [
        'enabled' => true,
        'instance-url' => 'https://example.com',
        'bearer' => 'my_bearer',
    ],
],

Als Erstes setzen wir ein Secret, das an verschiedenen Stellen im Plugin gebraucht wird, um Routen und Webhooks abzusichern.

Wir wollen die Panel-Statistiken und später ggf. ein paar andere Funktionen nutzen, die eine Datenbank benötigen, deshalb müssen wir einen Pfad konfigurieren, in dem die Datenbank abgelegt werden kann.

Als Nächstes konfigurieren wir die allgemeinen Einstellungen, um zu Mastodon und anderen Services posten zu können. Ich setze die bevorzugte Sprache noch auf Englisch, weil ich in Deutsch und Englisch schreibe und obwohl Deutsch die Standardsprache in Kirby ist, poste ich auf Englisch.
Wie oben beschrieben, habe ich zwei Templates für meine Notizen, nur diese beiden Templates sollen ein Posting bei Mastodon auslösen. Also setze ich allowedTemplates auf diese beiden Templatenamen. Abschließend sage ich dem Plugin noch, in welchem Feld mein Text gespeichert ist. In unserem Beispiel text.

Jetzt noch schnell Mastodon konfigurieren. Hierzu setzen wir die Instanz und einen API-Token, den man unter https://example.com/settings/applications erzeugen kann. Die neue App benötigt mindestens die folgenden Scopes:

• read
• write:media
• write:statuses

Den erzeugten Token sollten wir irgendwo ablegen, wo er sicher ist.

Ab sofort wird das IndieConnector-Plugin einen Mastodonbeitrag erstellen, sobald wir eine neue Notiz in Kirby veröffentlichen.

Raycast Plugin

Raycast-Erweiterungen werden in TypeScript geschrieben, die UI-Komponenten in React. Die Erweiterung, die wir schreiben werden, besteht aus einer Mischung. Wir benötigen einerseits das Formular, in dem wir den Beitrag schreiben können und wir müssen diesen Beitrag natürlich in Richtung Kirby schicken.

Ich werde hier nicht erklären, wie man eine neue Erweiterung erstellt, das lässt sich hier nachlesen und ist auch relativ leicht. Ich gehe an dieser Stelle davon aus, dass es bereits ein Dummy-Plugin gibt. Ich veröffentliche außerdem meinen Code bei GitHub.

Sobald wir die Entwicklung mit npm run dev starten, taucht das neue Plugin bei Raycast auf und kann getestet werden.

Wir beginnen mit dem simplen Teil, dem Formular. Wir legen ein neues Command an, wenn das bisher nicht geschehen ist, und geben das Formular aus:

export default function Command() {
return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm onSubmit={handleSubmit} />
        </ActionPanel>
      }
    >
      <Form.TextArea id="posttext" title="Post Text" placeholder="Enter your text" enableMarkdown={true} />
      <Form.TextField id="url" title="Bookmark" placeholder="https://" value={url} onChange={setUrl} />
      <Form.TextField id="title" title="Titel" placeholder="Titel" />
      <Form.Separator />
      <Form.Checkbox id="autopublish" title="Autopublish" label="Autopublish" defaultValue={preferences.autopublish} />
      <Form.Checkbox id="skipUrl" title="Skip URL" label="Skip URL" defaultValue={preferences.skipurl} />
      <Form.Checkbox id="externalPost" title="External Post" label="External Post" defaultValue={preferences.posse} />
    </Form>
  );
}

Das sorgt für eine Darstellung wie oben im Screenshot. Woher die defaultValues kommen, erkläre ich gleich. In der Form kannst du sehen, dass beim Abschicken handleSubmit() aufgerufen wird. Hier findet der eigentliche API-Call statt:

  async function handleSubmit(values: Values) {
    try {
      const baseUrlNoTrailingSlash = preferences.baseurl.replace(/\/$/, "");
      const response = await fetch(`${baseUrlNoTrailingSlash}/posse`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${preferences.secret}`,
        },
        body: JSON.stringify(values),
      });

      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }

      const responseData = (await response.json()) as ApiResponse;
      await Clipboard.copy(responseData.url);

      const status = responseData.status == "draft" ? "Posted as draft" : "Published your post";

      showToast({ title: status, message: "The URL has been copied to your clipboard" });
      await delay(1000);
      await closeMainWindow();
    } catch (error) {
      console.error(error);
      showToast({ style: Toast.Style.Failure, title: "Error", message: "Failed to submit form" });
    }
  }

Wir rufen die API mit fetch auf und greifen dabei auf zwei Werte zu, die später in den Einstellungen der Erweiterung festgelegt werden können, der Basis-URL und einem Secret. Auf diese Weise vermeiden wir das Hardcodieren privater Daten im Quellcode.

Wir setzen einen POST-Call ab und reichen diesem 1:1 die Werte rein, die wir aus dem Formular bekommen.

Läuft etwas schief, erzeugen wir einen Fehler, der unten im catch Block für eine Fehlermeldung unter dem Formular sorgt.

Läuft alles gut, lesen wir die Antwort der API aus, diese wird eine URL zum neuen Beitrag enthalten, welche wir prompt in die Zwischenablage kopieren, dem User das mitteilen und dann nach einer Sekunde das Fenster schließen.

Ich habe noch eine kleine Feinheit ergänzt, die beim Aufruf der Erweiterung in Form eines Hooks stattfindet:

  const [url, setUrl] = useState("");

  // Read clipboard when the form is opened
  useEffect(() => {
    async function fetchClipboard() {
      const text = await Clipboard.readText();

      if (text) {
        if (text.startsWith("http")) {
          setUrl(text);
        }
      }
    }

    fetchClipboard();
  }, []);

Sobald das Formular angezeigt wird, lese ich die Zwischenablage aus und prüfe, ob sie einen Link enthält. Wenn dem so ist, setze ich den lokalen State url. Ein Blick in den Code des Formulars zeigt, dass diese URL dann als Value für das Bookmark-Feld gesetzt wird. Denn oftmals kopiere ich eine URL im Browser, um sie dann direkt zu teilen. Mit dieser kleinen Feinheit spare ich mir dann ein paar Tastenkürzel.

Damit könnten wir jetzt eigentlich arbeiten, noch fehlen uns aber alle Werte aus den Einstellungen, also alles, was unter preferences gespeichert ist. Hier der passende Typ zu besseren Übersicht:

interface Preferences {
  secret: string;
  baseurl: string;
  autopublish: boolean;
  posse: boolean;
  skipurl: boolean;
}

Bevor wir etwas anderes im Command tun, holen wir uns die Einstellungen:

  const preferences = getPreferenceValues<Preferences>();
  const markdown = "You need to provide a secret in the extension preferences.";
  if (!preferences.secret) {
    return (
      <Detail
        markdown={markdown}
        actions={
          <ActionPanel>
            <Action title="Open Extension Preferences" onAction={openExtensionPreferences} />
          </ActionPanel>
        }
      />
    );
  }

Einstellungen

Einstellungen können auf zwei Ebenen abgelegt werden, die wir beide nutzen:

1. Global für alle Commands
2. Für ein spezielles Command

Die Preferences werden in der package.json definiert.

baseUrl und secret werden wir global ablegen. Sollten wir einmal weitere API-Calls hinzufügen, benötigen wir sie dort auch. Alle anderen Einstellungen brauchen wir nur im Formular und werden sie deshalb nur für das Command ablegen.

Auf oberster Ebene der package.json legen wir einen neuen Eintrag an und definieren die Werte:

  "preferences": [
    {
      "name": "secret",
      "title": "Secret key",
      "description": "Enter your API token",
      "type": "password",
      "required": true
    },
    {
      "name": "baseurl",
      "title": "Base URL",
      "description": "Enter your API endpoint",
      "type": "textfield",
      "required": true
    }
  ],

Rufen wir die Erweiterung das erste Mal auf, müssen wir zunächst Werte für diese globalen Einstellungen eingeben. Damit sind diese auf jeden Fall gesetzt.

Nun definieren wir Einstellungen, die für unser Command gelten und für mögliche weitere Kommandos nicht von Nutzen sind:

"commands": [
    {
      "name": "new-note",
      "title": "New Note",
      "description": "Creates a new note",
      "mode": "view",
      "preferences": [
        {
          "name": "autopublish",
          "title": "Autopublish",
          "description": "Automatically publish the note",
          "type": "checkbox",
          "default": false
        },
        {
          "name": "skipurl",
          "title": "Skip URL",
          "description": "Skip URL",
          "type": "checkbox",
          "default": true
        },
        {
          "name": "posse",
          "title": "POSSE",
          "description": "Post to other platforms",
          "type": "checkbox",
          "default": true
        }
      ]
    }
],

Dieses Mal sind wir nicht ganz so streng. Alle Einstellungen habe einen Standardwert, sie müssen also nicht zwingen konfiguriert werden. Wir benutzen diese Einstellungen für die drei Checkboxen im Formular. So muss ich beispielsweise nicht jedes Mal anklicken, dass mein Beitrag automatisch veröffentlicht werden soll.

Im Formular greifen wir bereits mit defaultValue={preferences.posse} auf die Werte zu.

Sobald du npm run dev beendest, steht das Plugin dir normal in Raycast zur Verfügung und du kannst es wie andere Plugins auch nutzen.

Damit sind wir startklar. Uns fehlt allerdings noch die Empfangsseite in Form einer Kirby-Route.

Die Kirby-Route

Wir haben mehrere Möglichkeiten, die Kirby-Route anzulegen:

1. Direkt in der config.php
2. Als Plugin

Da der Code identisch ist, überlasse ich diese Entscheidung dir. Ich habe ein Plugin, in dem solche speziellen Routen sammle, damit meine config.php übersichtlich(er) bleibt. Der Code ist aber in beiden Fällen derselbe.

'routes' => [
    [
        'pattern' => 'posse',
        'method' => 'POST',
        'action' => function () {
            // FOLLOWING CODE
        }
    ]
]

Die Route soll unter /posse aufgerufen werden, und zwar als POST-Request. Bevor wir etwas machen, prüfen wir, ob der Token korrekt ist. Wir holen uns die Daten aus der Anfrage, die im POST-Request übermittelt wurden. Das machen wir mit den Kirby Request-Methoden¹. Dort schauen wir, ob ein Authorization Header mit unserem Token vorhanden ist:

$request = kirby()->request();
$requestData = $request->data();

$authHeader = $request->header('Authorization');
$token = $authHeader ? explode(' ', $authHeader)[1] : null;

if ($token !== option('mauricerenck.posse.token', '')) {
    return new Response('Unauthorized', 'text/plain', 401);
}

In der config.php müssen wir nun unser Token festlegen. Stimmt das Token aus der URL nicht überein, brechen wir sofort ab und geben eine entsprechende Rückmeldung. Um ganz sicherzugehen, setzen wir den Standardwert des Tokens auf einen leeren Text. Stimmt das Token, läuft das Skript weiter.

Damit wir eine neue Notiz anlegen können, benötigen wir erst einmal eine Seite, unter der wir dies machen können. In meinem Fall gibt es die Seite notes, die wiederum in Jahre unterteilt ist. Wir versuchen uns, diese Seite zu holen, und sollte sie nicht gefunden werden, brechen wir sofort ab:

$year = date('Y');
$parent = kirby()->page('notes/' . $year);

if (is_null($parent)) {
    return new Response('Not Found', 'text/plain', 404);
}

Im folgenden Verlauf können wir sicher sein, dass alle Voraussetzungen erfüllt sind.

Im nächsten Schritt schnappen wir uns die übermittelten Werte und setzen nötige Variablen und fangen dabei gleich möglicherweise fehlende Werte ab:

$template = 'note';
$autoPublish = isset($requestData['autopublish']) && filter_var($requestData['autopublish'], FILTER_VALIDATE_BOOLEAN);

$newData = [
    'title' => empty($requestData['title']) ? 'Bookmark ' . date('Y-m-d') : trim($requestData['title']),
    'text' => !empty($requestData['posttext']) ? trim($requestData['posttext']) : '',
    'icSkipUrl' => isset($requestData['skipUrl']) && filter_var($requestData['skipUrl'], FILTER_VALIDATE_BOOLEAN),
    'enableExternalPosting' => isset($requestData['externalPost']) && filter_var($requestData['externalPost'], FILTER_VALIDATE_BOOLEAN)
];

In meinem Beispiel unterscheiden wir zwischen zwei Templates, einer einfachen Textnotiz note und einem Lesezeichen bookmark. Zunächst setzen wir das Standard-Template note.

Wir empfangen alle Daten als String, das trifft auch auf Boolesche Werte zu. Mit $autoPublish = isset($requestData['autopublish']) && filter_var($requestData['autopublish'], FILTER_VALIDATE_BOOLEAN); können wir den Wert sicher in eine echte Boolesche Variable umwandeln. Das machen wir für alle passenden Werte.

Unsere Kirby-Seite benötigt einen Titel. Wurde in Raycast kein Titel eingeben, setzen wir einen generierten Titel.

Der eigentliche Text wird im Normalfall vorhanden sein, aber wir stellen trotzdem sicher, dass zumindest ein leerer Text hinterlegt wird.

Wir setzen außerdem zwei Werte des IndieConnectors, nämlich ob die URL zur Notiz an den Mastodon-Post gehängt werden soll und ob wir überhaupt bei Mastodon (oder Bluesky) posten wollen.

Danach prüfen wir, ob eine gültige URL übermittelt wurde. Wenn ja, unterscheide ich an dieser Stelle zwischen einer reinen Textnotiz und einem Lesezeichen. Das spiegelt sich im Titel, dem Link und dem Template wider:

if (!empty($url) && V::url($url)) {
    $newData['title'] = 'Link: ' . $newData['title'];
    $newData['link'] = $url;
    $template = 'bookmark';
}

Bevor wir gleich die Seite anlegen, müssen wir noch eine Sache sicherstellen: Wir müssen Duplikate vermeiden. Erstellen wir eine Notiz mit dem Titel test und tun dies ein zweites Mal, wirft uns Kirby ein Duplikat um die Ohren und legt die zweite Seite nicht an, weil sie die erste überschreiben würde. Das müssen wir also abfangen:

$slug = Str::slug($newData['title']);
$unusedSlug = false;
while ($unusedSlug === false) {
    $unusedSlug = is_null($parent->childrenAndDrafts()->find($slug));
    if (!$unusedSlug) {
        $slug = $slug . '-' . uniqid();
    }
}

Wir erzeugen den Slug für die neue Seite, dieser entspricht später dem Ordnernamen. Dann durchlaufen wir eine Schleife und prüfen darin, ob es bereits eine Seite mit diesem Slug gibt. Wenn ja, ergänzen wir eine ID. Beim zweiten Durchlauf sollte dann keine Seite mehr gefunden werden und wir sind auf der sicheren Seite. Sollte wider Erwarten doch eine Seite existieren, läuft die Schleife so lange, bis das nicht mehr der Fall ist.

Jetzt können wir endlich die neue Seite erstellen. Dazu benötigen wir die entsprechenden Berechtigungen, die wir uns mit impersonate() holen:

kirby()->impersonate('kirby');
$newPage = Page::create([
    'parent'  => $parent,
    'slug'     => $slug,
    'template' => $template,
    'content' => $newData
]);

Neue Seiten sind zunächst immer ein Entwurf. Wenn wir bei Raycast angegeben haben, dass die Seite sofort publiziert werden soll, müssen wir das jetzt noch tun:

if ($autoPublish === true) {
    $newPage->changeStatus('listed');
}

Wir sind fast fertig. Ganz zum Schluss wollen wir Raycast noch das Ergebnis mitteilen:

$response = [
    'url' => $newPage->url(),
    'status' => $setToPublished ? 'published' : 'draft',
];

return new Response(json_encode($response), 'application/json', 201);

Anhand dieser Antwort zeigen wir in Raycast eine Erfolgs- oder Fehlermeldung an. Und kopieren die URL der Notiz in die Zwischenablage.

Verfeinerungen

Mit unserem können wir jetzt in Windeseile neue Notizen erzeugen und diese auch direkt als Mastodon- oder Bluesky-Beitrag veröffentlichen und das mit einer überschaubaren Code-Basis.

Wer mag, kann jetzt noch in die Verfeinerung gehen. Wir könnten uns etwa Antworten bei Bluesky zurück in die Notizen holen. Dazu werde ich demnächst einen Beitrag veröffentlichen, denn der IndieConnector kann das bereits.

Den Quellcode für die komplette Kirby-Route findest du hier:

Den Quellcode für das Raycast-Plugin findest du hier:

Viel Spaß beim Posten!

Da hätten wir einerseits das Bloggerrolle-Plugin, welches den Dienst anpingt und zum anderen ein Kirby-Plugin zum automatischen Veröffentlichen von Seiten, was wir bei konzentrik für uns entwickelt haben. Das war im Grunde schon fertig und brauche nur noch ein paar Vorbereitungen, damit die Releases auch funktionieren.

(Und irgendwie bin ich noch sehr unzufrieden darüber, wie die Detailseiten meiner Projekte aussehen)

Ich erwähnte dort, dass ich schon lange vorhabe, externe Antworten, Likes und Reposts selbst zu holen. Das ist allerdings nicht ganz so trivial, wie es auf den ersten Blick scheint.

Leider bin ich bisher nicht dahintergekommen, warum das Einsammeln von Antworten über brid.gy nicht mehr so funktioniert. Aktuelle Logs kann ich mir nicht ansehen, weil sie mit Fehlermeldungen abbrechen, bevor eine Webmention geschickt wird.

Es ist also doch Zeit, dieses Feature in Angriff zu nehmen und es bei GitHub von der Upcoming-Feature-Liste zu streichen. Und genau das habe ich getan.

Postet man automatisch zu Mastodon oder Bluesky, speichert das IndieConnector-Plugin (IC) schon die URLs zu den Posts. Im Falle von Mastodon kann man zudem selbst eine URL hinterlegen (das wird es dann auch für Bluesky geben).

Das sind schon einmal gute Voraussetzungen für das Feature, denn IC weiß somit, wo es nachschauen kann, um Reaktionen einzusammeln. Mastodon stellt bereitwillig drei Endpunkte bereit, um an Likes, Reposts und Replies zu kommen – wunderbar.

Es gibt schon ein paar Lösungen und Beschreibungen, wie man das mit JavaScript lösen kann. Die funktionieren gut, für die Plugins muss (und will) ich jedoch den PHP-Weg gehen.

Der IC geht alle URLs durch, holt sich die Antworten und schickt dann eine Webmention an sich selbst. Jede Response hat eine virtuelle Seite mit entsprechenden Microformats. Von hier an läuft der gewohnte Webmention-Ablauf ab. Ein Grund, warum ich diesen Weg gewählt habe. Auf diese Weise muss ich wirklich nur das Abholen bauen und nicht noch einen weiteren Weg öffnen, um Daten abzulegen usw.

Anders als bei der JavaScript-Lösung muss ich mir merken, welche Reaktionen ich schon verarbeitet habe, damit ich nicht ständig dieselben Webmentions verschicke und unnötige Last auf den Systemen erzeuge. Ich merke mir also für jeden Mastodon-Endpunkt die letzte bekannte Response-ID und beende dann den Ablauf, sobald die erreicht ist.

Das klappt bisher super.

Seit ein paar Stunden sitze ich nun aber hier und grübele, warum diese Webmentions nicht ankommen wollen. Verschickt werden sie. Und so cool ich diese ganze Technik finde, asynchrone Prozesse zu debuggen ist und bleibt fummelig. Ich versuche einzelne Schritte mit Unit-Tests abzudecken, aber manchmal – wie gerade – sitze ich dann trotzdem da und schaue fragend auf den Bildschirm.

Ich hoffe, dass ich das Problem schnell gelöst bekomme. Dann hätte ich den kompletten Ablauf für Mastodon schon fertig und müsste für Bluesky "nur" noch das Abholen bauen (denn danach läuft es genauso weiter wie bei Mastodon).

Update
Ich habe eine falsche (alte) URL für meinen Webmention-Endpunkt benutzt und alle Webmentions ins Nirvana geschickt, deshalb kamen sie nicht an 🤦🏼‍♂️

Anfang des Jahres habe ich hier davon erzählt, dass ich von Feedly zu Feedbin gewechselt bin. Ich bin weiterhin sehr zufrieden mit Feedbin, habe dort zahlreiche Blogs und andere Seiten abonniert – meine eigene auch.

Vor einigen Tagen fiel mir dann etwas auf: Ich hatte einen neuen Beitrag veröffentlicht, ihn aber gar nicht bei Feedbin gesehen. Seltsam. Vielleicht habe ich einfach übersehen? Das lässt sich leicht nachprüfen. In der Liste aller Abos suchte ich nach meinem Namen und ließ mir die Details zu meinem Feed anzeigen:

Anders als hier im Screenshot zu sehen, stand dort allerdings, dass mein letztes Update im Feed zwei Jahre zurückliegt. Entweder ist die Zeit wie im Fluge vergangen, oder etwas stimmte mit meinem Feed nicht.

Im W3C-Validator sah alles gut aus, keine Fehler, nur ein paar Warnungen wegen relativer Anker-Links. Ich verwende außerdem einen freien Dienst, der mich per Mail informiert, wenn mein Feed defekt ist (ich komme gerade einfach nicht auf den Namen …).

Ich entschied mich, ein kleines Feature zu nutzen, über das ich gar nicht reden darf. Ich veröffentliche einen Blogpost, zeigte ihn aber ausschließlich im RSS-Feed an. Dort berichtete ich von meinen Problemen und bat um Kommentare.

Ich kam mir sehr clever vor, denn nur Abonnent:innen meines RSS-Feeds können diesen Beitrag sehen und kommentieren. Wer kommentiert, empfängt also eindeutig meinen Feed.

Es wurde fleißig kommentiert! Mein Feed war also lesbar und viele der Kommentare bestätigten mir dies. Das half mir sehr, vielen Dank an alle, die sich gemeldet haben!

Irgendwas musste Feedbin also an meinem Feed stören. Ich prüfte erneut im Detail das XML. Alles sah okay aus, Tags mit Datum waren gesetzt, das Datum im richtigen Format usw. Alles sah gut aus. Aber etwas musste meinen Feed von anderen unterscheiden!

Nach kurzem Grübeln vermutete ich, dass eine ganze bestimmte Zeile schuldig sein könnte: mein Stylesheet.

Ruft man einen RSS-Feed im Browser auf, wird er entweder direkt heruntergeladen oder man sieht den Quelltext, mit dem man wenig anfangen kann. Es gibt aber die Möglichkeit (wie bei HTML) Styles einzubetten, sodass der Feed dann im Browser auch für Menschen lesbar ist. Das habe ich gemacht.

Ich nahm das Styling also raus, schob die Änderungen auf den Server und abonnierte meinen Feed neu. Seitdem trudeln bei mir wieder Beiträge ein. Es lag tatsächlich am Styling.

Das ist ein wenig ärgerlich, aber nicht weltbewegend. Ich hatte auch bisher nicht die Muße herauszufinden, ob es an meinem speziellen Code lag, oder ob Feedbin damit generell nicht umgehen kann. Vielleicht teste ich das später noch einmal, gerade gibt es aber wichtigere Aufgaben.

Dank meiner tollen Feed-Leser:innen habe ich nun aber wieder einen RSS-Feed, der überall funktioniert – vielen Dank. Und vielleicht wollt ihr ja eure Feeds auch mal prüfen, das wäre doch ärgerlich, wenn es an so einer Kleinigkeit scheitert.

Welche Feeds ich abonniert habe, kann man übrigens jetzt auch in meiner Blogroll sehen!

Mit einem kleinen Trick blende ich nicht zu übersetzende Felder im Kirby Panel aus.

Im Kirby Panel verwende ich zahlreiche Felder, die nicht übersetzt werden müssen oder sollen. Das sind Felder wie Kategorien oder Tags, aber auch bestimmte Settings, die ich setzen kann und die für alle Sprachen gleichermaßen gelten.

Meine Hauptsache ist Deutsch, dort setze ich die Werte, wechsle ich dann auf Englisch, kann ich die Felder nicht bearbeiten und die Werte kommen aus der Deutschen Seite:

Da mich diese Felder in der Übersetzung nicht wirklich interessieren, fragte ich mich häufig, warum sie denn überhaupt sichtbar sein müssen.

Das Ausblenden von nicht übersetzbaren Feldern ist im Kirby Panel leider nicht möglich, also musste eine andere Lösung her.

Eigenes Panel-CSS

Wenn ich die Felder nicht via config ausblenden kann, dann kann ich das zumindest über CSS tun. Erfreulicherweise ist es möglich, eine eigene CSS-Datei in das Panel zu laden und somit Styles zu überschreiben.

Das ist nützlich, wenn man das Panel beispielsweise für einen Kunden branden will – oder eben Felder ausblenden.

Zunächst gilt es, die CSS-Datei zu laden. Das passiert in der config.php

'panel' => [
    'css' => '/assets/css/panel.css'
]

Schon wird die Datei im Panel geladen und wir können unser Unwesen treiben.

Ein Blick in den Inspektor zeigt auf, dass jedes Feld von einigen div umgeben ist. Leider wird die Information, dass ein Feld deaktiviert ist, erst auf zweiter Ebene in den Tree geschrieben:

Ausblenden müssen wir .k-column, damit nicht nur das Feld unsichtbar ist, sondern auch der Platz freigegeben wird. Blenden wir nur das Feld aus, bleibt Whitespace in Höhe des Feldes erhalten.

Wir wissen allerdings erst eine Ebene tiefer, dass das betroffene Feld deaktiviert wurde. Die Information steht im data-Attribute data-disabled="true".

Dank neuer CSS-Features und dem glorreichen has() Selektor können wir indirekt auf das Parent-Element von Data-Disabled-Div zugreifen:

div:has(> [data-disabled='true']) {
    display: none;
}

Hurra! So einfach geht das inzwischen. Wir schauen also nach divs, deren Kinder das Attribut data-disabled='true' haben und blenden diese dann aus.

Im Ergebnis sieht das dann so aus:

Zu sehen sind nur noch die relevanten Felder, alles andere ist ausgeblendet. Ganz optimal funktioniert das nicht, weil die Felder sich im Nachhinein nicht den Platz nehmen, den sie jetzt haben könnten, aber das ist eine Kleinigkeit. Viel wichtiger ist, dass nun nur noch relevante Felder gezeigt werden.

Auf diese Weise könnte ich jetzt weitere Anpassungen vornehmen, sollte mir mal wieder etwas auffallen oder ich das Panel-Design anpassen wollen.

Viel Spaß beim selbst ausprobieren.

Nach über zehn Jahren mit Kirby als CMS fürs Bloggen habe ich jetzt endlich einen Arbeitsablauf, der mir wirklich gefällt.

Kirby ist ein tolles CMS, um ein Blog zu betreiben. Daten werden in Textdateien gespeichert, Texte können in Markdown geschrieben werden. Das Panel – Kirbys Verwaltungsoberfläche – lässt sich bis ins kleinste Detail individualisieren und jede Seite kann ihr individuelles Set an Feldern haben.

Das macht es möglich, das eigene Blog auf die eigenen Bedürfnisse anzupassen und Dinge so zu gestalten, dass sie das Bloggen besonders einfach machen.

Aber so sehr ich die Oberfläche mag und mir coole Features und Plug-ins dafür gebaut habe, einen großen Haken hatte das ganze Set-up all die ganzen Jahre: Ich schreibe meine Texte nicht direkt im CMS, sondern in einem Markdown-Editor.

Das war mal VS Code, mal iA Writer, dann Ulysses, wieder iA Writer und zwischendurch immer mal wieder Obsidian. Alle hatten ein Problem gemeinsam: Sobald ein Text in Kirby war, liefen die Kirby-Version und die Version im Editor auseinander.

Wer kennt das nicht: Ein Text ist online und beim direkten Blick auf die Seite fällt dann doch noch ein Fehler auf. Ein Link ist nicht korrekt gesetzt oder irgendwo ein Vertippper. Also korrigiere ich diesen Fehler schnell im Panel, damit die Änderung sofort online ist.
Anfangs, als die Motivation noch groß war, korrigierte ich diese Fehler auch noch in meinem Dokument im Markdown-Editor. Aber um ehrlich zu sein, irgendwann hatte ich darauf keinen Bock mehr, schob es nach hinten und ließ es schließlich ganz sein.
Die Texte auf der Webseite sind dann also in einer anderen Form, als sie im Editor sind.

Das wäre alles kein Problem, wenn ich die Texte nicht gerne auch eben im Editor hätte, der für mich auch eine Art Datenbank ist. Ich bin großer Freund des Zettelkastens. Ich halte es auch für sinnvoll, Texte immer irgendwie als Datei lokal liegen zu haben, anstatt nur online.

Das erste Problem ist also die Synchronität zwischen beiden Welten.

Das zweite Problem ist der Zustand beider Dokumente. Neben dem Text gibt es noch zahlreiche Metadaten, wie Tags, ein Datum und den eigentlichen Zustand, also ob ein Dokument ein Entwurf, nicht gelistet oder publiziert ist. Einige Editoren haben dafür Lösungen parat.

Die Markdown-Editoren

Ich habe zwar anfangs VS Code zum Schreiben von Markdown verwendet, aber bin irgendwann davon ab. VS Code ist nun mal ein Code-Editor und viele Funktionen, die ich von einem Texteditor erwarte, sind nicht enthalten, ließen sich vielleicht nachrüsten, haben dann aber umgekehrt eigentlich auch nichts in einem Code-Editor zu suchen. Ich bin also schnell wieder zu anderen Apps gewechselt.

iA Writer

iA Writer ist einer der besten Editoren da draußen. Er ist minimal gestaltet und bietet dennoch alle Funktionen, die man sich beim Schreiben wünscht. Neben dem hübschen (und kaum vorhandenen) Interface haben mir besonders die Grammatikhelfer gefallen. Ich benutze iA Writer seit der ersten Version und dieses Feature war eines meiner meistgenutzten. Ich kann mir verschiedene Wortarten anzeigen lassen und auf diese Weise schnell Füllwörter und unnötige Adjektive ausfindig machen.

Hier sieht man iA Writers Stilprüfung:

Und so bunt kann es aussehen, wenn man alle Wortarten hervorheben lässt:

Alles lässt sich im Detail ein- und ausschalten:

Ganz besonders toll ist aber die Möglichkeit, Texte über verschiedene Dienste/APIs direkt aus iA Writer heraus zu veröffentlichen:

Wie man sieht, sind hier die populärsten Schnittstellen vertreten. Besonders interessant ist hier sicherlich Micropub, weil der Standard nicht auf ein bestimmtes CMS zugeschnitten ist. Für meinen Fall war das allerdings nur eingeschränkt nützlich.

Sebastian hat ein ganz großartiges Plug-in dafür geschrieben, welches es mir auch möglich machte, über mein Smartphone kurze Posts als Notizen zu veröffentlichen – und eben meine Texte aus iA Writer heraus zu veröffentlichen.

Das Plug-in wird leider nicht weiterentwickelt. Es lief zwar immer noch mit den letzten Kirby 4 Versionen, wurde mir dann aber doch etwas zu riskant; eine nicht gewartete Schnittstelle zum eigenen CMS ist langfristig keine gute Idee.

Außerdem gibt es auch hier ein wesentliches Problem: Die Kommunikation führt nur in eine Richtung, vom Editor ins Blog, aber nicht wieder zurück. Es ist eben nur zum Veröffentlichen gedacht.

Wenn es um das Verwalten meiner Texte geht, bin ich mit iA Writer bedauerlicherweise auch nie so richtig warm geworden. Die Datei/Ordner-Ansicht empfand ich nie als übersichtlich genug, gerade wenn es darum geht, dass Dokumente auch in Verbindung miteinander stehen und in verschiedene "Rubriken" einsortiert werden sollen.

Ulysses

Ulysses ist hier etwas besser aufgestellt. Neben Ordnern lassen sich auch noch Projekte anlegen, sodass sich verschiedene Inhalte gut gruppieren lassen. Das hilft mir ganz gut, weil ich nicht nur für mein eigenes Blog Texte schreibe und für jedes Blog ein eigenes Projekt anlegen kann.

Auch Ulysses kommt mit einer eigenen Stil- und Grammatikprüfung, die ganz hervorragend funktioniert; wenn auch nicht so plakativ wie bei iA Writer. Dafür sind die Empfehlungen hier häufig etwas ausgefeilter und umfangreicher, meist werden mehrere Vorschläge gemacht, wie man etwas besser eleganter formulieren könnte.

Offensichtlich ist die Oberfläche ebenfalls recht minimalistisch, wenn auch lange nicht so minimal wie bei iA Writer. Generell empfinde ich iA Writer immer als etwas "runder", mag vor allem den iA Writer Font besonders gerne.

Auch bei Ulysses lassen sich Texte direkt veröffentlichen. Wie zu sehen ist, sind auch hier alle gängigen Kanäle vertreten. Jedoch leider kein Micropub, stattdessen aber eine direkte Schnittstelle zu Micro.blog. Ein Feature-Request vor ein paar Jahren konnte hier bisher leider nichts bewegen.

Auch hier bleibt allerdings das Problem des fehlenden Rückkanals. Texte können zwar veröffentlicht, aber nicht wieder zurück in den Editor geholt werden.

Obsidian

Die Eierlegende Wollmilchsau.

Obsidian ist Open Source und kostenlos. Entsprechend weit verbreitet ist es. Es gibt zahlreiche Themes und mindestens ebenso viele Plug-ins, um den Editor zu erweitern.

Der Lieblingssport einiger User besteht darin, Obsidian mit Plug-ins und selbstgebauten Konstrukten so weit zu tunen, dass es wie ein Projektmanagementsystem funktioniert; daraus dann endlose Videoreihen bei YouTube zu machen und sich schließlich darüber zu beschweren, wie kompliziert Obsidian ist und zu erklären, dass man jetzt zu Notion wechselt.

Keine Panik. Obsidian kann so sein, dazu muss man sich aber schon anstrengen. Nach der Installation ist Obsidian erst einmal ein Texteditor, mit ein paar grundlegenden, hilfreichen Funktionen.

Der Griff zu einem Theme hat meinerseits dennoch nicht lange gedauert, weil ich unbedingt etwas Minimales haben wollte. Ich verwende Obsidian Boom mit einigen zusätzlichen Einstellungen, damit alles schön clean aussieht:

Weil ich den Font von iA Writer so toll finde, habe ich ihn mir heruntergeladen und installiert. Er ist frei verfügbar und eingeschränkt nutzbar.

Von Haus aus hat Obsidian keine besonderen Stil- oder Grammatik-Features. Das lässt sich über ein Plug-in nachrüsten. Das funktioniert dann ähnlich gut wie bei Ulysses:

Hier verwende ich das LanguageTool Integration Plug-in. Leider wird es nicht mehr aktiv weiterentwickelt, ich hoffe, es bleibt uns noch eine Weile erhalten, oder dass sich jemand findet, um die Entwicklung wieder aufzunehmen.

Ich habe außerdem eines der Focus-Plug-ins im Einsatz, welches sämtliche UI-Elemente ausblendet und damit eine ähnlich minimale Darstellung herstellt, wie iA Writer und Ulysses.

Plug-ins zum Synchronisieren von Texten und Einstellungen gibt es einige. Die meisten davon sind allerdings eher Backup-Syncs oder zum Synchronisieren zwischen verschiedenen Rechnern und Mobilgeräten gedacht. Hier habe ich mich vor einiger Zeit dazu entschieden, Obsidian Sync zu nutzen. Das scheint mir am stabilsten zu laufen und ich kann die Entwickler auf diese Weise etwas unterstützen. Die Versions-Historie hat mir bereits einmal den Hintern gerettet, als ich mit einem eigenen Plug-in herumprobiert habe; war den Kauf also schon wert.

Damit kommen wir zum wesentlichen Thema: dem Veröffentlichen von Texten. Auch hier gibt es einige Plug-ins, aber nichts, was mit Kirby funktionieren würde. Allerdings durfte ich freudig feststellen, dass Obsidian-Plug-ins in TypeScript geschrieben werden, etwas, womit ich mein Geld verdiene, also gut beherrsche.

Umso weniger konnte ich mich dann beherrschen und habe losgelegt, ein eigenes Plug-in zu schreiben.

Obsidian und Kirby verbinden

Mein Problem habe ich ja nun häufig genug benannt, mir fehlt die Möglichkeit, Texte zwischen Kirby und meinem Editor synchron zu halten. Das betrifft den Text selbst, aber auch dessen Metadaten.

Um das herzustellen, brauche ich jeweils ein Plug-in für Kirby und eines für Obsidian. Das Kirby-Plug-in muss eine Schnittstelle bereitstellen, die mir das Auslesen und Senden von Daten an Kirby ermöglicht. Das Obsidian-Plug-in muss diese Anfragen ausführen und mit den Ergebnissen arbeiten, also etwa meine lokalen Dateien aktualisieren.

Ich bin das Ganze experimentell in einem extra dafür erstellen Obsidian Vault angegangen. Ich wollte ein wenig herumspielen und dabei keine Angst vor Datenverlust haben müssen.

Dabei hat sich herausgestellt, dass ich vier Endpunkte brauche, die folgende Aufgaben erfüllen:

• Daten in Kirby aktualisieren
• Daten in Obsidian aktualisieren
• Eine neue Seite in Kirby anlegen
• Eine neue Seite in Obsidian anlegen

Im Grunde werden damit drei Fälle abgedeckt:

1. Ich habe einen neuen Text in Obsidian erstellt und will diesen nun in Kirby veröffentlichen
2. Ich habe bereits einen Text in Kirby, den ich bisher nicht lokal habe und möchten diesen Text in Obsidian "herunterladen"
3. Ich habe den Text sowohl in Obsidian als auch in Kirby und will eines von beidem aktualisieren

Das Obsidian-Plug-in

Wie schon erwähnt, werden Obsidian-Plug-ins mit TypeScript geschrieben, was mir sehr liegt, weil ich damit mein Geld verdiene. Ich habe mich also ran gesetzt und erst einmal geschaut, wie das in Obsidian alles so funktioniert. Glücklicherweise ist das alles recht naheliegend und mithilfe von Ollama in meiner IDE kam ich ohne viel Grundwissen über die Obsidian API schnell voran.

Zunächst musste ich mir überlegen, was ich synchronisieren möchte. Natürlich den Text selbst, aber auch eine Handvoll, Metadaten. Das Problem hier sind die unterschiedlichen Formate, in denen Metadaten abgelegt werden. Wären diese identisch, bräuchte ich gar keine Plug-ins, sondern könnte vermutlich einfach direkt mit den Dateien arbeiten.

Obsidian legt Metadaten im Frontmatter Format ab. So sieht das gerade beim Schreiben für diesen Artikel aus:

---
type: text
aliases: 
date: 2024-12-05
channel: blog
status: draft
sync: false
slug: 
title: 
intro: 
tags:
---

Die Darstellung in Obsidian sieht dann wie folgt aus:

Kirby hingegen legt die Metadaten in einem leicht abweichenden Format ab:

Title: 

----

Intro: 

----

Text:

----

Date: 

----

Tags: 

Wie man sieht, unterscheiden sich beide leicht in ihrem Format und den Inhalten. Während Metadaten wie das Datum und Tags bei beiden direkt in die Textdatei geschrieben werden, identifiziert Kirby den Status der Seite (draft, unlisted, listed) über den Ordner, legt diese Information also nicht direkt in der Datei ab.

Die meiste Übersetzungsarbeit übernimmt Kirby für mich. Da ich in der API alle Kirby-Klassen und -Methoden nutzen kann, muss ich mir um das Format keine Gedanken machen. Ich schicke lediglich alle Metadaten und den Text als separate Datensätze mit.

Ich habe bereits ein Kirby-Plug-in namens "Internal API" in dem ich diverse Endpunkte bereitstelle, um Kleinkram zu machen oder auf dem Mac Informationen anzuzeigen. Das Plug-in konnte ich also einfach erweitern. Letztendlich handelt es sich um ein Plug-in, welches ein paar Routen bereitstellt.

Dank des relativ simplen Anwendungsfalls, konnte ich hier den klassischen CRUD¹ Weg gehen. Wobei eigentlich nur CRU, weil ich das Löschen bewusst weggelassen habe. So sehen die Endpunkte aus:

[
    'pattern' => 'ENDPOINT/(:any)/(:any)/(:any)',
    'method' => 'VERB',
    'action' => function ($channel, $folder) {
        $request = kirby()->request();
        $requestData = $request->data();
        $requestHeaders = $request->headers();

        if ($requestHeaders['Authorization'] !== 'Bearer ' . option('mauricerenck.obsidian.token')) {
            return new Response('Unauthorized', 'text/plain', 401);
        }

        // DO STUFF

        return new Response(json_encode($data), 'application/json');
    },
],

Diese Route gibt es dreimal, dabei unterscheidet sich jeweils das Verb:

• Create -> 'method' => 'POST'
• Read -> 'method' => 'GET'
• Update -> 'method' => 'PUT'

Der ENDPOINT heißt in Wirklichkeit natürlich auch anders.

Ich hätte hier eine Route wählen können, die alle drei Fälle abfängt, habe mich aber dagegen entschieden und mich auf etwas Code-Duplizierung eingelassen, um alles etwas klarer getrennt und letztendlich übersichtlicher zu gestalten.

Wie man sieht, wird jeder Request durch einen Token abgesichert. Jede Anfrage muss den richtigen Token im Header mitschicken, sonst wird sie abgelehnt. Damit sichere ich die Endpunkte ab, sonst könnte ja jeder einfach Daten schicken und lesen.

Die Struktur

Bevor wir weiter machen, ein paar Worte zur zugrunde liegenden Struktur. Auf meiner Webseite habe verschiedene Bereiche, die ich nutze, um Inhalte ein wenig voneinander trennen zu können. Im Wesentlichen sind das Blog, Hub, Notes und demnächst noch ein vierter Bereich. Hier spreche ich von Kanälen.

Damit ich nicht endlose lange Verzeichnislisten habe, sind die jeweiligen Kanäle noch einmal aufgeteilt, im Blog und in den Notizen nach dem Jahr und im Hub nach Themen.

Die Struktur ist also:

/blog/2025/article-slug/template.en.md

oder

/hub/built-with-kirby/article-slug/template.en.md

Mit einem Blick auf die Metadaten in Obsidian dürftest du davon schon etwas gesehen haben:

channel: blog
slug: article-slug

Eine Ebene fehlt, das Jahr bzw. das Thema. Hier habe ich mich dazu entschlossen, die Struktur in Obsidian nachzubilden. Schaut man sich also den Obsidian-Verzeichnisbaum an, ist dieser identisch mit der Kirby-Struktur:

Das Verzeichnis ATTACHMENTS kann ignoriert werden, hier legt Obsidian verknüpfte Dateien ab, Bilder z.B.
Wie man aber sieht, gibt es hier die Jahres-Verzeichnisse, wie es sie auch bei Kirby gibt.

Auf diese Weise baue ich mir dann im Obsidian-Plug-in die API-Endpunkt-URL zusammen:

const options = {
    url: `${this.settings.apiBaseUrl}/${channel}/${folder}/${slug}`,
    method: 'POST|PUT|GET',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.settings.apiToken}`
    },
    body: JSON.stringify(data)
};

Wir haben eine Base-URL, das ist die URL meiner Webseite plus den oben erwähnten ENDPOINT. Gefolgt vom Kanal, z.B. blog, dem folder, für diesen Beitrag also ´2025´. Schließlich der slug. Der Slug ist letztendlich der Dateiname der Markdown-Datei in Obsidian, bei Kirby ist es der Verzeichnisname des Posts.

Fall 1: Eine neue Seite erstellen

Einer der Anwendungsfälle ist das Erstellen einer neuen Seite in Kirby. Ich habe also in Obsidian bereits einen Text geschrieben. Dieser soll jetzt – wir bleiben beim Beispiel – im Blog veröffentlicht werden.

Damit nicht einfach wild synchronisiert wird, was gar nicht synchronisiert werden soll, habe ich einen Sync-Haken eingebaut. Nur, wenn dieser aktiviert ist, kann eine Datei überhaupt synchronisiert werden. Das sieht man weiter oben im Screenshot.

Überhaupt: Die Frage, was wann wie synchronisiert wird und ob es bereits synchronisiert wurde, stellte sich ziemlich früh.

Hier wird eine Mischung aus verschiedenen Status und dem Sync-Haken tätig.

how-to-burn-money ist nicht synchronisiert und als Idee abgelegt. Das bedeutet, dass es meist nur ein paar Stichpunkte gibt und ich noch gar nicht weiß, ob daraus mal ein Text wird.

obsidian-kirby-sync ist bereits in Arbeit, aber wurde noch nicht synchronisiert. Er liegt als neue Datei vor, hat aber seinen Weg noch nicht in Richtung Kirby gefunden.

example 2 wird synchronisiert und liegt als draft bei Kirby.

example wird synchronisiert und wurde veröffentlicht, allerdings nicht gelistet.

sociabli wird synchronisiert, wurde veröffentlicht und ist im Blog sichtbar.

In unserem Beispiel haben wir also einen Artikel in Arbeit, dieser wurde aber bisher nicht synchronisiert. Im Plug-in müssen wir daher zunächst lokal ein paar Daten sammeln, damit wir diese an Kirby schicken können:

const data = await this.readFileData(file);
const channel = data.frontmatter.channel;
const currentYear = new Date().getFullYear();
const folder = file.parent?.name || currentYear.toString();

try {
    // REQUEST CODE FROM ABOVE WITH THIS CHANGES
    // url: `${this.settings.apiBaseUrl}/${channel}/${folder}`,
    // method: 'POST',

    const response = await requestUrl(options);

    if (response.status !== 200) {
        console.error(`Failed to fetch API data from ${channel}`);
        return \{\};
    }

    this.syncFile(file, response.json);
}

Zunächst einmal lesen wir die aktuelle Markdown-Datei aus, holen uns aus den Frontmatter-Daten den Kanal und holen uns das aktuelle Jahr. Schließlich legen wir fest, wie der Folder lauten wird. Hat die Datei ein übergeordnetes Verzeichnis? Dann nehmen wir dessen Namen, wenn nicht, das Jahr. Der letzte Fall dürfte eigentlich nie eintreten, ich will hier aber auf Nummer sicher gehen.

Wie der eigentliche API-Call dann funktioniert, habe ich oben schon gezeigt. Weil wir einen neuen Artikel erstellen, ist es ein POST Request.

Schlägt der Aufruf aus irgendeinem Grund fehl, wird der Fehler geloggt und abgebrochen. Ist alles gut gelaufen, bekommen wir von der API die gespeicherten und durch Kirby angereicherten Daten zurück.

Läuft etwas komplett schief, greift der catch Block und macht Alarm:

catch (error) {
    console.error(`Error: Could not create page`);
    new Notice(`Error: Could not create page`);
    this.updateStatus('Error: Could not create page');
    return \{\};
}

Erst wird der Fehler geloggt, ich zeige außerdem noch eine Notification an und unten in der Statuszeile von Obsidian auch noch eine Meldung. Es sollte also nicht zu übersehen sein.

Kirby-Plug-in

Wie oben in der Route schon gezeigt, empfängt Kirby die Daten und prüft den Token. Kanal, Folder und Slug werden über die URL mitgegeben und direkt in die Route hereingereicht, der Text steht im POST-Body und muss ausgelesen werden.

Als Nächstes prüfe ich dann, ob es den Folder überhaupt gibt. Sollte das nicht der Fall sein, breche ich sofort ab:

$parent = kirby()->page($channel . '/' . $folder);

if (is_null($parent)) {
    return new Response('Not Found', 'text/plain', 404);
}

Nun geht es daran, die Daten ins Kirby-Format zu bringen und zu speichern:

$newData = [
    'title' => $requestData['frontmatter']['title'],
    'intro' => $requestData['frontmatter']['intro'],
    'text' => $requestData['content'],
    'tags' => $requestData['frontmatter']['tags'],
];

kirby()->impersonate('kirby');
$page = Page::create([
    'parent'  => $parent,
    'slug'     => Str::slug($requestData['frontmatter']['title']),
    'template' => 'post',
    'content' => $newData
]);

Ich baue mir hier also ein Array zusammen, das ich dem Page::create Aufruf hineingeben kann. Zusätzlich erzeuge ich hier noch einen slug aus dem Titel. Als Template dient mein Standard post Template.

Damit erzeugt Kirby eine neue Seite und liefert mir diese auch direkt zurück, sodass ich gleich über $page darauf zugreifen kann.

Erst einmal schaue ich aber, welchen Status die Seite haben soll. Ich könnte sie nämlich in Obsidian auch gleich so einstellen, dass sie direkt veröffentlicht wird:

if (in_array($requestData['frontmatter']['status'], ['listed', 'unlisted'])) {
    $page->changeStatus($requestData['frontmatter']['status']);
}

Der initiale Zustand ist immer draft weshalb ich hier nur listed und unlisted abfragen muss. Ist eines davon gesetzt, wird die Seite entsprechend veröffentlicht.

Jetzt reichern wir die Daten noch etwas an und schicken sie zurück an Obsidian:

$data = [
    'frontmatter' => [
        'tags' => $page->tags()->split(','),
        'date' => $page->date()->toDate('c'),
        'status' => $page->status(),
        'title' => $page->title()->value(),
        'intro' => $page->intro()->value(),
        'sync' => true,
        'slug' => $page->slug(),
        'channel' => $channel,
    ],
    'modified' => $page->modified('c'),
    'content' => $page->text()->value(),
    'folder' => $page->parent()->uid(),
    'headers' => $requestHeaders,
];

return new Response(json_encode($data), 'application/json');

Hier ist wesentlich, dass ich das Datum und den Slug zurückliefere, denn diese Information hatte Obsidian bisher nicht. Im Obsidian Plug-in gibt es eine Methode zum Aktualisieren der lokalen Datei, die diese Daten in Empfang nimmt.

Daten in Obsidian empfangen

Um unnötige Aktualisierungen und Endlosschleifen zu unterbinden, prüfe ich zunächst, ob es überhaupt Änderungen gibt:

const originalContent = await this.app.vault.read(file);
const frontmatter = this.app.metadataCache.getFileCache(file)?.frontmatter;

let updatedContent = originalContent;

Ich lese mir also den aktuellen, lokalen Stand aus. Diesen schreibe ich in updatedcontent, das wirkt etwas schräg, erklärt sich aber gleich.

Zuerst geht es an die Metadaten:

if (frontmatter) {
    const frontmatterEndIndex = originalContent.indexOf("---", 3) + 3;
    const existingFrontmatter = parseYaml(originalContent.slice(3, frontmatterEndIndex - 3));
    const updatedFrontmatter = { ...existingFrontmatter, ...apiData.frontmatter };
    const newFrontmatterBlock = `---\n${stringifyYaml(updatedFrontmatter)}---`;

    updatedContent = newFrontmatterBlock + originalContent.slice(frontmatterEndIndex);
} else {
    apiData.frontmatter.sync = true;
    updatedContent = `---\n${stringifyYaml(apiData.frontmatter)}---\n${originalContent}`;
}

Ich mache aus dem Frontmatter-Text-Block erst einmal ein Objekt. Dieses überschreibe ich dann einfach mit den Daten aus der API. Ich kümmere mich hier gar nicht um einzelne Felder oder so, da bin ich ziemlich risikobereit. Am Ende schreibe ich die Daten in updatedContent und hänge den Text unten dran.

Hat die Datei noch gar kein Frontmatter, übernehme ich 1:1 die Daten aus der API. Das kommt später zum Tragen, wenn wir in Obsidian eine neue Datei mit den Daten aus Kirby anlegen.

Jetzt aktualisiere ich noch den eigentlichen Inhalt:

if (apiData.content) {
    const frontmatterEndIndex = updatedContent.indexOf("---", 3) + 3;
    updatedContent = updatedContent.slice(0, frontmatterEndIndex) + "\n" + apiData.content;
}

Auch hier nehme ich stumpf das, was die API liefert.

Jetzt wird es tricky, es geht um den Slug. Der lokale Dateiname soll immer dem remote Slug entsprechen, also müssen wir da ran:

const newSlug = apiData.frontmatter.slug;
const currentTitle = file.name.replace(/\.md$/, ""); 
console.log(`Checking slug ${file.path} vs ${newSlug}.md`);

if(apiData.folder !== file.parent?.name) {
    console.log(`Moving file ${file.path} to ${apiData.folder}`);
    await this.moveFile(file, apiData.folder, newSlug);
} else if (newSlug && newSlug !== currentTitle) {
    console.log(`Renaming file ${file.path} to ${newSlug}.md`);
    await this.renameFile(file, newSlug);
}

Ich schnappe mir den Slug von der API. Ich schnappe mir den aktuellen Dateinamen und entferne die Dateierweiterung. Hat sich der Folder geändert, bewege ich die Datei und benenne sie nach dem neuen Slug um. Hat sich nur der Slug geändert, nenne ich die Datei um.

Auch das greift schon ein wenig dem Voraus, was wir für andere Syncs brauchen.

Final schreiben wir nun noch die Datei, sollte das nötig sein:

if (originalContent !== updatedContent) {
    this.pluginStatus == "pulled"
    await this.app.vault.modify(file, updatedContent);
}

this.updateStatus('Sync Complete');

Fall 2: Eine Seite herunterladen

Der zweite Fall betrifft die Gegenrichtung. Es gibt bereits eine Seite in Kirby und ich möchte sie nun auch in Obsidian haben. Das betrifft meist alte Artikel, die ich geschrieben habe, bevor ich die Plug-ins am Start hatte.

Auf Seiten von Kirby ist das der simpelste Fall. Die Route horcht auf den Kanal, den Folder und Slug. Es handelt sich um einen GET Request. Wie immer wird erst der Token geprüft und dann hole ich mir die Seite:

$page = kirby()->page($channel . '/' . $folder . '/' . $slug);

if (is_null($page)) {
    return new Response('Not Found', 'text/plain', 404);
}

Gibt es sie nicht, wird das entsprechend quittiert und der Prozess beendet. Gibt es die Seite, wird das gleiche Array wie schon beim Create erzeugt und an Obsidian zurückgeliefert.

Damit das funktioniert, brauche ich die Möglichkeit, Folder und Slug etc. anzugeben, dafür gibt es einen Dialog:

Sehr spartanisch, ich weiß, es soll erst einmal nur funktionieren. Hier muss ich den Slug von Kirby wissen. Ich muss also ins Panel schauen. Das ist nicht ganz optimal, da der Fall aber sehr selten vorkommt, ist das okay für mich.

Klicke ich submit wird der GET-Request abgeschickt:

const options = {
    url: `${this.settings.apiBaseUrl}/${channel}/${folder}/${slug}`,
    method: 'GET',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.settings.apiToken}`
    },
};

Da ich hier wie beim Create dieselbe Datenstruktur zurückbekomme, kann ich im Erfolgsfall einfach dieselbe Methode aufrufen, die ich am Ende von Fall 1 aufgerufen habe. Die Logik bleibt dieselbe. Kirby schickt mir alle Daten zurück, insbesondere hier den Slug, der nun genutzt wird, um die Datei entsprechend zu benennen und ggf. ins richtige Verzeichnis zu schieben.

Fall 3: Kirby mit lokalen Daten aktualisieren

In diesem Fall synchronisieren sich beide Enden bereits. Ich möchte jetzt gezielt lokale Änderungen zu Kirby schicken. Ein PUT Request. Auf Seite von Kirby funktioniert dieser fast genauso, wie der POST Request.

Ich hole mir wieder die betroffene Seite, erstelle mir ein Array mit den neuen Daten und rufe dann ein update statt eines creates auf:

$page->update($newData);

Danach gebe ich die Daten der Seite wie schon beim Create zurück und Obsidian kann die lokale Datei wieder aktualisieren, sofern nötig.

Fall 4: Die lokale Datei aktualisieren

Der letzte Fall. Auch hier synchronisieren sich beide Enden bereits und wir wollen jetzt Änderungen, die ich im Panel vorgenommen habe, auch lokal aktualisieren.

Lokal haben wir bereits alle Daten, die wir brauchen, um den GET Request abzusetzen. Für Kirby ein leichtes Spiel. Ich hole mir die Seite, lese die Daten aus und liefere sie wieder im bekannten Format zurück an Obsidian.

Tja, und Obsidian kann dann einfach wieder die Methode zum Aktualisieren der Datei nutzen.

Der Feinschliff

Wagemutig hatte ich mich zunächst dazu entschieden, beim lokalen Öffnen einer Datei immer einen Sync auszuführen und mir Daten aus Kirby zu holen (sofern der Haken gesetzt ist, natürlich).

Ich meinte, das Risiko eingehen zu können, weil ich in Obsidian auf Änderungen gelauscht habe und immer dann in Richtung Kirby synchronisiert habe, wenn Obsidian die Datei gespeichert hat.

Das war etwas zu mutig und führte im Produktivbetrieb dann zu Datenverlust. Ich hatte lokal schon viel geschrieben, remote stand noch ein "Test" im Text und irgendwie schaffte ich es, die Datei zu öffnen, ohne dass sie vorher in Richtung Kirby geschickt wurde. Resultat: Mein Text war weg, es lachte mir ein freudiges "Test" an. Dank Obsidian Sync konnte ich dann aber den letzten Stand wiederherstellen.

Ich habe mich dann gegen automatisches Synchronisieren entschieden …

Ich hatte von Beginn an schon die Möglichkeit, einen Sync per Befehl zu starten. Dazu rufe ich die Befehlszeile mit cmd+p auf und tippe kirby. Dann kann ich auswählen, was ich machen möchte:

Wie man sieht, sind hier alle vier Fälle aufgelistet. Bei "Create page from remote" geht der oben gezeigte Dialog zur Eingabe des Slugs auf. Ansonsten werden die beschriebenen Prozesse ausgelöst.

Ein solches Command kann man in Obsidian wie folgt anlegen:

this.addCommand({
    id: 'kirby-pull-remote',
    name: 'Update local file',
    checkCallback: (checking: boolean) => {
        const activeFile = this.app.workspace.getActiveFile();

        if (activeFile && activeFile.extension === "md") {
            if (!checking) {
                this.pluginStatus = "pulling";
                this.handleFileModify(activeFile, true);
            }

            return true;
        }

        return false;
    }
});

Ein paar Abfragen, um sicherzugehen, dass auch alle Voraussetzungen erfüllt sind, dann wird der Sync aufgerufen. Die anderen Befehle funktionieren ähnlich.

Schließlich habe ich noch ein Plug-in im Einsatz, mit dem ich den Dateien Icons geben kann. Dieses Plug-in zapfe ich an, um entsprechend dem Datei-Status ein passendes Icon zu setzen, das hat man oben im Screenshot schon gesehen.

Fazit

Mit diesem Set-up bin ich bisher sehr zufrieden. Ich habe immer alles auf dem gleichen Stand. Dank Obsidian Sync läuft mein Plug-in auf allen Geräten.

Natürlich passiert noch ein wenig mehr, oben sieht man schon den pluginStatus, der sicherstellt, dass es keine Loops gibt und sich nichts überschneidet. In Kirby wandle ich noch die Obsidian-Syntax für Bilder in einen Kirbytag um. Aus ! [ [obsidian-8.png ] ] wird dann ( image: obsidian-8.png ) wenn die Page in Kirby gerendert wird (die Leerzeichen habe ich ergänzt, damit die Tags nicht ersetzt werden).

Apropos Bilder! Die synchronisiere ich bislang nicht, die müssen also extra hochgeladen werden. Das wäre noch ein nettes Feature für die Zukunft.

Ich kann also munter synchronisieren, mein Obsidian sieht dank Theme und Font toll aus und ich kann dort sehr angenehm schreiben. Dank Obsidian Sync habe ich keine Angst vor Datenverlust und kann auf allen Geräten auf meinen Vault zugreifen. Ich habe gute Stil- und Grammatikprüfung über das Plug-in und ich kann den Status meiner Dateien auf den ersten Blick im Verzeichnisbaum sehen.

Es gibt noch massives Potenzial für Verbesserungen. Das alles ist wild zusammen gehackt, weil ich viel ausprobiert und neu gelernt habe. Deshalb sind beide Plug-ins noch etwas davon entfernt, veröffentlicht werden zu können. Und ich bin auch gar nicht sicher, wie weit ihr dafür überhaupt Bedarf besteht. Ihr könnt mir ja mal einen Kommentar schreiben.

Ich werde hier jetzt noch einmal die Rechtschreibprüfung drüber schicken und dann via Obsidian eine neue Seite bei Kirby anlegen. Wie jedes Mal freue ich mich aufs Neue darüber, dass das jetzt möglich ist.

Wenn ein Link zu unserer Webseite geteilt wird, soll in der Vorschau ein automatisch generiertes Bild angezeigt werden. Dazu benutzen wir mein Kirby-Plugin.

Wenn wir unsere Blogposts, Notizen oder andere Seiten bei Mastodon, Bluesky oder wo auch immer teilen, sollen diese Posts gut aussehen. Deshalb wäre es schön, in der jeweiligen Vorschau auch ein Bild anzuzeigen. Das ist über spezielle Meta-Tags möglich. Allerdings haben wir nicht unbedingt für jede Seite, die wir teilen wollen auch ein Bild parat. Für diesen Fall können wir automatisch ein Bild erzeugen.

Das Plugin ermöglicht es uns, verschiedene Szenarien umzusetzen. Im Wesentlichen geht es um drei verschiedene Fälle, die wir abdecken wollen:

1. Wir haben bereits eine Grafik erstellt, die beim Teilen verwendet werden soll
2. Wir haben keine Grafik, eine neue soll erstellt werden
3. Wir haben eine Grafik, diese soll in eine neu zu erstellende Grafik eingebunden werden

Der erste Fall dürfte klar sein: Wir haben bereits ein Bild und wollen das verwenden, ohne dass es verändert wird.

Die beiden anderen Fälle sind etwas komplexer. Haben wir gar keine Grafik zur Verfügung, soll eine neue Grafik erstellt und 1:1 benutzt werden. Im dritte Fall haben wir ein Beitragsbild, das soll aber nicht 1:1 als Bild zum Teilen verwendet, sondern mit Informationen angereichert werden.

Alle diese Fälle werden wir mit dem OG-Image-Plugin umsetzen.

Das Plugin installieren

Das OG-Image-Plugin kann wie alle Kirby-Plugins installiert werden. Ich halte eine Installation über Composer für die beste Methode, weil hier auch unkompliziert Updates installiert werden können, ohne dass wir selber nach Updates gucken müssen. Um das Plugin zu installieren, wechseln wir in der Kommandozeile zunächst in das Verzeichnis, in dem unsere Webseite liegt und geben den folgenden Befehl ein:

composer require mauricerenck/ogimage

Wer die Installation nicht über Composer vornehmen will, kann sich hier eine Zip-Datei herunterladen und diese dann im Verzeichnis der Webseite unter sites/plugins¹ entpacken, sodass ein ogimage Verzeichnis erstellt wird.

Das Plugin ist nun bereit zum Einsatz und kann von uns jetzt konfiguriert werden. Dazu brauchen wir allerdings ein paar Dinge.

Vorbereitungen

Das Plugin braucht zwei Dateien, ohne die es nicht arbeiten kann:

1. Ein Grafik-Template im PNG-Format
2. Eine TrueType Schrift

Das Template kann theoretisch beliebig groß sein, empfohlen wird aber ein Bild der Größe 1600x930 Pixel. Das ist auch die Standardeinstellung für das Plugin. Du musst dir also zunächst ein solches Bild erstellen. Meines sieht so aus:

Wie du siehst, habe ich mich für eine simple Farbfläche entschieden. Unten zeige ich die URL der Webseite an und auf der rechten Seite habe ich einen Bereich ausgeschnitten, sodass ich einen transparenten Kreis habe. Warum ich das gemacht habe, erkläre ich später.

Ich habe mir außerdem die Schrift geschnappt, die ich auch auf meiner Webseite benutze.

Beide Dateien lege ich nun im Verzeichnis assets/og-image ab. Wir werden gleich in der Konfiguration darauf zugreifen.

Das Template verwenden

Jetzt geht es an die Konfiguration des Plugins, noch weiß es nichts von unserem Template oder der Schrift.

Wir öffnen die Konfiguration von Kirby unter site/config/config.php²

Wir legen eine neue Konfiguration für das Plugin an und geben auch direkt den Pfad zu unserer Grafikvorlage an:

"mauricerenck.ogimage" => [
    "image.template" => "assets/og-image/template.png",
],

Wie du siehst, handelt es sich um einen relativen Pfad, immer ausgehend vom Document-Root deiner Kirby-Seite.

Alle künftigen Optionen finden nun innerhalb von "mauricerenck.ogimage" => [ … ] statt.

Den Titel setzen

Als Nächstes konfigurieren wir unseren Text. Das OG-Image soll am Ende den Titel der Seite in der gewählten Schriftart anzeigen. Dazu legen wir ein paar Optionen fest. Wir beginnen mit dem Pfad zur Schriftdatei, genauso, wie wir es beim Template getan haben:

"font.path" => "assets/my-webfont.ttf",

Jetzt können wir das Bild bereits aufrufen, mehr müssten wir nicht tun. Rufen wir also einen Beitrag im Browser auf und hängen /og-image an die URL, erscheint unser neues Bild:

Wie du sieht, hat das Plugin unser Template verwendet und den Titel mit der passenden Schriftart eingefügt. Der Transparente Bereich ist auf einmal farbig, das ändern wir später noch.

Kümmern wir uns erst einmal um unseren Titel. Zum einen soll der nicht so oben links in die Ecke gequetscht werden, außerdem ist er in der Farbe kaum lesbar. Wir werden nun also:

1. Die Farbe ändern
2. Die Position anpassen

"font.color" => [255, 255, 255],
"title.position" => [70, 215],

Die Schriftfarbe setzen wir mit font.color auf einen RGB-Wert, in diesem Beispiel weiß. Die Position des Titels setzen wir mit title.position. Das Array enthält zwei Werte, den X und Y Wert in Pixel.

Rufen wir das Bild im Browser nun erneut auf … ändert sich nichts. Das Plugin zeigt das Bild nicht nur einfach an, sondern legt eine Bilddatei an. Das tut es, damit nicht bei jedem Aufruf ein neues Bild berechnet werden muss. Teilen wir einen Link, könnte es ja sein, dass in kurzer Zeit sehr viele User das Bild sehen, würde es dann jedes Mal neu erzeugt werden, würde der Server vermutlich schnell in die Knie gehen.

Um die Änderungen zu sehen, müssen wir das vorhandene Bild erst einmal löschen.

Nach dem Löschen und Neuladen im Browser sehen wir das neue Bild:

Das sieht schon besser aus. Der Text ist lesbar und klebt nicht in der Ecke. Er ragt aber in den farbigen Bereich und der Zeilenabstand ist mir persönlich noch zu hoch. Das passen wir hiermit an:

"font.lineheight" => 1.5,
"title.charactersPerLine" => 16,

Die Zeilenhöhe legen wir mit font.lineheight fest. Mit title.charactersPerLine legen wir fest, nach wie vielen Zeichen der Text umbrechen soll, sodass er nicht in die farbige Fläche ragt.

Mit dieser Konfiguration sieht das Bild jetzt so aus:

Das gefällt mir schon ganz gut. Jetzt geht es aber ans Eingemachte. Wir werden uns im Folgenden um die oben beschriebenen, drei Szenarien kümmern.

Drei Variationen

Eine selbsterstellte Grafik

Haben wir bereits eine Grafik, die auch beim Teilen angezeigt werden soll, muss kein neues Bild erzeugt werden. Für den Fall bietet das Plugin die Möglichkeit, ein OG-Image-Feld zu konfigurieren. Standardmäßig prüft das Plugin, ob ein Feld mit dem Namen ogImage vorhanden ist. Dieser Feldname kann mit der Option field in der config.php angepasst werden. In unserem Fall passt er so und wir erstellen das Feld im Panel:

ogImage:
    type: files
    label: OG Image
    layout: cards
    multiple: false
    image:
      cover: true

Wir erstellen das Feld als Datei-Feld, in dem wir immer nur ein Bild selektieren können.

Das Plugin macht den Rest. Sobald das OG-Image abgerufen wird, schaut es in das konfigurierte Feld, ist ein Bild vorhanden, wird es ausgespielt, wenn nicht, ein neues erzeugt.

Eine Grafik einbetten

Wenn ein Beitragsbild vorhanden ist, soll dieses in unser OG-Image eingebettet werden, dafür haben wir den transparenten Bereich auf der rechten Seite angelegt.

Zuerst müssen wir dem Plugin sagen, wo es unser Beitragsbild findet. Damit es an der richtigen Position zu sehen ist, schneiden wir es zu und schieben es nach rechts:

"heroImage.field" => 'hero',
"heroImage.cropsize" => [610, 610],
"heroImage.position" => [900, 163],

Unser Kreis ist etwa 600 Pixel groß, ich habe etwas Toleranz hinzugenommen. Unser Beitragsbild liegt im Feld hero und wird auf 610x610 zugeschnitten. Wir schieben es 900 Pixel nach rechts und 163 nach unten.

Jetzt können wir ein Beitragsbild setzen und das OG-Image abrufen:

Den Kreis füllen

Wenn kein Beitragsbild vorhanden ist, wird der Kreis derzeit mit einer Farbe gefüllt. Selbstverständlich können wir diese Farbe ändern. In dieser Variante wollen wir den Kreis einfach mit der Hintergrundfarbe des Templates auffüllen, sodass er unsichtbar wird:

"heroImage.fallbackColor" => [40, 46, 59],

Wie schon bei der Schriftfarbe setzen wir auch hier einen RGB-Wert. Dieser entspricht nun der Hintergrundfarbe der Grafik. Unser OG-Image sieht nun so aus:

Sehr schlicht, aber funktional.

Ein Logo anzeigen

Für mich eine Spur zu schlicht. Ich würde stattdessen lieber ein Logo anzeigen. Dafür gibt es eine weitere Option, parallel zur Fallback-Farbe, kann ich auch ein Fallback-Bild konfigurieren.

Zuerst habe ich mir ein Bild erzeugt, welches das Logo an der passenden Position enthält:

Jetzt kann ich dieses Bild wieder unter assets/og-image ablegen. Ich nenne es fallback.png. In der Konfiguration setze ich nun einfach den Bildpfad:

"heroImage.fallbackImage" => "assets/og-image/fallback.png",

Rufe ich das OG-Image nun erneut auf, sieht es so aus:

Das sieht doch schon ganz gut aus. Jetzt können wir natürlich weiter verfeinern, mit Schriftgrößen und Position experimentieren, aber damit lasse ich dich jetzt alleine.

Lass uns zum Abschluss noch einmal auf die gesamte Konfiguration schauen:

"mauricerenck.ogimage" => [
    "image.template" => "assets/og-image/template.png",

    "font.path" => "assets/spectral-regular-webfont.ttf",
    "font.color" => [255, 255, 255],
    "font.lineheight" => 1.5,

    "title.charactersPerLine" => 16,
    "title.position" => [70, 215],

    "heroImage.field" => 'hero',
    "heroImage.cropsize" => [610, 610],
    "heroImage.position" => [900, 163],
    "heroImage.fallbackColor" => [40, 46, 59],
    "heroImage.fallbackImage" => "assets/og-image/fallback.png",
],