excalidoc

Die Excalidraw-Komponente ermöglicht das Einbetten von 👉 Excalidraw-Zeichnungen in MDX-Dokumente.

Leerer Editor

Ein leerer Editor zeigt standardmässig das Excalidraw-Logo - erst beim klicken auf "Edit" wird der Editor geladen und ein leeres Dokument wird angezeigt.

import Excalidoc from '@tdev/excalidoc/Component';

<Excalidoc id="c0c6e611-7adc-4bc1-8cd8-4abf4276f3a0"/>

http://localhost:3000

Laden...

Optionen

height

Höhe des Editors als CSS-Property (z.B. 500px, standard: 600px).

Die maximale Höhe (max-height) ist fest auf 70vh gesetzt.

allowImageInsertion

Erlaubt das Einfügen von Bildern.

default: false

useExcalidrawViewer

Verwendet den Excalidraw-Viewer (Read-Only) in der Vorschau anstatt das Vorschau-Bild.

Dies kann nützlich sein, wenn eine Zeichnung gross ist und gezoomt werden können muss.

Einfügen von Bildern allowImageInsertion

Standardmässig können keine Bilder eingefügt werden, um die Dateigrösse möglichst klein zu halten. Mit dem Parameter allowImageInsertion kann das Einfügen von Bildern erlaubt werden.

<Excalidoc id="1bdb72b1-822a-4fc4-9758-eb61e7e20abc" allowImageInsertion/>

http://localhost:3000

Laden...

Vorlagen

Es lassen sich auch die Standardwerte für ein Excalidraw-Dokument festlegen.

defaultElements

Enthält die Szenenelemente beim ersten Laden des Editors.

Am einfachsten wird eine Excalidraw-Zeichnung als .excalidraw exportiert und dessen Elemente dann eingefügt.

require('bild.excalidraw').elements

defaultFiles

Enthält eine vorlage auch Bilder, so müssen diese ebenfalls mitgelifert werden.

require('bild.excalidraw').files

defaultImage

Enthält das Anzeigebild, das standardmässig angezeigt wird.

<Excalidoc 
    id="25d2a32b-6072-4fb4-b8e1-34e5d57056aa"
    defaultElements={require('./assets/haus-des-nikolaus.excalidraw').elements}
    defaultFiles={require('./assets/haus-des-nikolaus.excalidraw').files}
    defaultImage={require('./assets/haus-des-nikolaus.png').default}
/>

http://localhost:3000

Laden...

Excalidraw viewer (useExcalidrawViewer)

Der Excalidraw-Viewer zeigt die Zeichnung im Read-Only-Modus an. Dies kann nützlich sein, wenn eine Zeichnung gross ist und gezoomt werden können muss.

<Excalidoc 
    id="25d2a32b-6072-4fb4-b8e1-34e5d57056aa"
    height="300px"
    useExcalidrawViewer
/>

http://localhost:3000

Laden...

Bibliotheken

Excalidraw bietet die Möglichkeit, Bibliotheken mit vorgegebenen Elementen einzubinden. Die Bibliotheken können wahlweise von 👉 https://libraries.excalidraw.com/ heruntergeladen oder selbst erstellt werden.

Im Beispiel werden 👉 Netzwerk-Topologie-Icons von @dwelle eingebunden - sie sind dann über die Bibliothek verfügbar.

Info

Bibliotheken können aktuell nicht von Usern selber hinzugefügt werden (bzw. nur über einen manuellen upload).

<Excalidoc 
    id="15d5d6b9-0ea8-4cf2-b3a7-31178daa85aa"
    libraryItems={require('./assets/network-topology-icons.excalidrawlib').libraryItems}
/>

http://localhost:3000

Laden...

Mit Code-Editor

Es kann auch eine Editor-Komponente mit dem Source-Code angezeigt werden:

import ExcalidocWithCodeEditor from '@tdev/excalidoc/Component/WithCodeEditor';

<ExcalidocWithCodeEditor id="c82833bc-d5c1-42d1-9e19-1c330a9873ad"
    defaultElements={require('./assets/circles.excalidraw').elements}
/>

http://localhost:3000

Laden...

Content-Editing Tools

Währenddem Docusaurus im development-Modus läuft, steht in der Toolbar das Edit Document-Icon zur Verfügung, um das Excalidraw-Dokument direkt zu bearbeiten.

Neue Excalidraw-Zeichnung erstellen

Eine neue Excalidraw-Zeichnung kann erstellt werden, indem im Markdown ein neuer Bild-Pfad angegeben wird:

![Neue Excalidraw-Zeichnung](./images/zeichnung.webp.new)

Das Plugin...

• erzeugt basierend auf der Dateiendung ein neues Bild beim angegebenen Pfad (erzeugt wenn nötig auch die Ordnerstruktur)
• überschreibt den Pfad im Markdown-Bild ohne das .new Suffix
• erstellt eine neue, leere Excalidraw-Zeichnung am angegebenen Pfad (hier ./images/zeichnung.webp.excalidraw)

![Neue Excalidraw-Zeichnung](./images/zeichnung.webp)

Unterstützte Bildformate:

• .png
• .jpg
• .jpeg
• .svg
• .webp

Installation

siteConfig.ts

const config: SiteConfigProvider = {
    tdevConfig: {
        excalidraw: {
            imageMarkupEditor: true,
            excalidoc: true
        }
    }
}