Loslegen

Online ausprobieren

Installation

Voraussetzungen

• Node, Version 22 oder höher
• eine Terminalanwendung, um Kommandozeilenprogramme zu starten
• Ein Texteditor mit Markdown-Unterstützung wird empfohlen

Projekt initialisieren

Das Paket muss zuerst via npm installiert werden, entweder alleinstehend oder in einem bestehenden Eleventy-Projekt:

npm i -D @lowfat/eleventy-plugin-lfp-docs

Danach kann entweder manuell oder via dem von LFP Docs bereitgestellten CLI-Tool eine Konfigurationsdatei erstellt werden (z.B. eleventy.config.js):

npx lfpdocs init

Jetzt können Dateien dem neu erstellten Verzeichnis /docs hinzugefügt werden, die Konfiguration wird in eleventy.config.js vorgenommen.

Verzeichnisstruktur

LFP Docs geht davon aus, in einem bestehendem Projekt installiert zu werden. Für alleinstehende Dokumentationsprojekte kann als config.dir.input auch "." gesetzt werden.

Falls die Standardeinstellung (/docs als config.dir.input) genutzt wird, sieht die grundlegende Verzeichnisstruktur eines LFP Docs-Projektes folgendermaßen aus:

.
├─ /docs
│  ├─ # hier werden Markdown-Dateien abgelegt
├─ eleventy.config.js
└─ package.json

Eleventy nutzt verzeichnisorientierte Pfadentwicklung, wodurch sich die URLs einzelner Dokumente aus ihrer Strukturierung innerhalb des Input-Verzeichnisses ergeben. Mit Permalinks kann dieses Verhalten überschrieben werden.

Konfiguration

Die Konfigurationsdatei wird entweder von der CLI-Anwendung generiert oder selbst erstellt sein; sie sieht in jedem Fall dem folgenden Beispiel ähnlich:

import lfpDocsPlugin from '@lowfat/eleventy-plugin-lfp-docs';
  
export default function (eleventyConfig) {
  eleventyConfig.addPlugin(lfpDocsPlugin, {
    // Konfiguration wird in diesem Object vorgenommen
  });

  return {
    dir: {
      data: '_data',
      includes: '_includes',
      input: 'docs',
      layouts: '_layouts',
      output: '_site',
    },
  };
}

Unter Konfiguration sind alle Konfigurationsmöglichkeiten aufgelistet.

Während grundsätzlich alle Konfigurationsmöglichkeiten für LFP Docs optional sind, empfiehlt es sich, die folgenden Einstellungen vorzunehmen:

• title: diese Einstellung fügt dem Projekt einen Titel im Menübereich der Seite hinzu.

Entwickeln

Das Projekt kann mit dem mitgelieferten Test-Server getestet werden:

npx lfpdocs dev

Der Test-Server sollte jetzt unter http://localhost:8080 erreichbar sein.

Build

Wenn das Projekt bereit für den Einsatz ist, kann es kompiliert werden:

npx lfpdocs build

Die generierten Inhalte werden in das spezifizierte Output-Verzeichnis (config.dir.output) geschrieben und können so sofort auf einen Server hochgeladen werden.