File Trees

Mit remark-file-trees lässt sich eine Verzeichnisstruktur als verschachtelte Markdown-Liste innerhalb von :::tree beschreiben. Das Plugin erzeugt daraus die bestehende Dir-Komponente mit derselben Darstellung und denselben Interaktionen wie bei der manuellen Verwendung. Verzeichnisse lassen sich durch Anklicken öffnen und schliessen.

Syntax und Wurzelverzeichnis

Jeder Baum hat genau ein Wurzelverzeichnis. Bei einem einzigen Eintrag auf der obersten Ebene wird dessen Name zur Wurzel und seine Unterliste zu deren Inhalt:

:::tree
- src
  - components
    - Button.tsx
  - index.ts
:::

http://localhost:3000

src

• components
  • Button.tsx
• index.ts

Ein einzelner Eintrag ohne Unterliste wird zu einem leeren Wurzelverzeichnis:

:::tree
- src
:::

http://localhost:3000

src

Bei mehreren Einträgen auf der obersten Ebene ergänzt das Plugin ein Wurzelverzeichnis namens /:

:::tree
- src
  - components
    - foo.docx
    - bar.js
  - utils
    - helper.ts
    - dir
      - index.ts
- public
  - index.html
  - favicon.ico
- README.md
:::

http://localhost:3000

/

• src
  • components
    • foo.docx
    • bar.js
  • utils
    • helper.ts
    • dir
      • index.ts
• public
  • index.html
  • favicon.ico
• README.md

Innerhalb der Wurzel ist ein Eintrag mit Unterliste ein Verzeichnis, ein Eintrag ohne Unterliste eine Datei. Dateiendungen und abschliessende / ändern diese Regel nicht. Namen, Verschachtelung und Reihenfolge bleiben erhalten; es wird nichts sortiert.

Geordnete und ungeordnete Listen sind möglich. Jeder Eintrag enthält einen Absatz mit seinem Namen und optional eine Unterliste. Namen dürfen normalen Text und Inline-Code enthalten. Inline-Code eignet sich beispielsweise für Zeichen, die Markdown sonst als Formatierung interpretieren würde:

:::tree
- project
  - `*notes*.md`
  - `data & images`
    - `a "quote".txt`
:::

http://localhost:3000

project

• *notes*.md
• data & images
  • a "quote".txt

Attribute

Die Attribute stehen direkt hinter tree, beispielsweise :::tree{openLevel=2 maxHeight="12rem"}.

Attribut	Standard	Verhalten
openLevel	Nicht gesetzt: alle Ebenen offen	Gibt die Anzahl der anfangs geöffneten Verzeichnisebenen an. 0 schliesst die Wurzel, 1 öffnet nur die Wurzel, 2 öffnet zusätzlich deren direkte Unterverzeichnisse.
maxHeight	Nicht gesetzt	Begrenzt die Höhe des gesamten Baums. Ohne Attribut gilt das bestehende Verhalten von Dir: keine zusätzliche Höhenbegrenzung. Bei Überlauf wird der Baum scrollbar.

maxHeight wird als CSS-Text an die Wurzelkomponente übergeben. Unterstützt werden beispielsweise 240px, 20rem, 50vh, 100%, none, calc(100vh - 2rem) und var(--tree-height). Prozentwerte benötigen eine passende Höhe des übergeordneten Elements; CSS-Variablen müssen definiert sein. maxHeight="0" wird nach der Attributkonvertierung wieder zur Zeichenfolge "0". Andere Zahlen ohne Einheit wie maxHeight="240", leere Werte und boolesche Werte führen zu einem Fehler. Die Gültigkeit anderer CSS-Ausdrücke prüft der Browser.

Die Wurzel zählt immer als erste Ebene, auch ein automatisch erzeugtes /. openLevel=2 und openLevel="2" sind gleichwertig: Das Plugin übergibt der bestehenden Komponente open={2}. Ohne openLevel übergibt es open, sodass alle Verzeichnisse anfangs offen sind. Die Verschachtelung der Verzeichnisdaten bleibt gleich.

Dieses Beispiel öffnet das Wurzelverzeichnis project und seine direkten Unterverzeichnisse src und public. components und utils starten geschlossen. Die Höhe ist begrenzt:

:::tree{openLevel=2 maxHeight="12rem"}
- project
  - src
    - components
      - Button.tsx
      - Header.tsx
      - Footer.tsx
    - utils
      - helper.ts
    - index.ts
  - public
    - index.html
    - favicon.ico
  - README.md
  - package.json
:::

http://localhost:3000

project

• src
  • components
  • utils
  • index.ts
• public
  • index.html
  • favicon.ico
• README.md
• package.json

Bei mehreren Einträgen zählt das ergänzte / mit: Hier sind /, src und public anfangs offen; components und images bleiben zunächst geschlossen.

:::tree{openLevel="2"}
- src
  - components
    - icons
      - Folder.tsx
  - index.ts
- public
  - images
    - logo.svg
  - index.html
:::

http://localhost:3000

/

• src
  • components
  • index.ts
• public
  • images
  • index.html

Mit openLevel=0 startet der Baum ganz geschlossen.

Automatischer Import

Das Plugin fügt bei Bedarf diesen Import hinzu:

import Dir from '@tdev-components/FileSystem/Dir';

Mehrere Bäume auf derselben Seite teilen sich den Import. Ist Dir bereits ausdrücklich aus diesem Modul importiert, wird dieser Import wiederverwendet. Auch import { default as Dir } from '@tdev-components/FileSystem/Dir'; wird erkannt.

Für einen Baum sind weder manuelles JSX noch eigene dir-Props oder Komponentenimports nötig.

Installation

Code

• src/plugins/remark-file-trees
• src/components/FileSystem/Dir.tsx

Das Plugin ist bereits in recommendedBeforeDefaultRemarkPlugins unter src/siteConfig/markdownPluginConfigs.ts registriert. Bei einer eigenen Plugin-Konfiguration gehört es vor die Standard-Remark-Plugins von Docusaurus. Die bestehende Directive-Parsing-Pipeline wird weiterverwendet:

docusaurus.config.ts

import fileTreesPlugin from './src/plugins/remark-file-trees/plugin';

const BEFORE_DEFAULT_REMARK_PLUGINS = [
    fileTreesPlugin
    /* weitere Plugins */
];