Klassenmanagement

Grundsätzlich werden jegliche Inhalte im Ordner /docs erstellt, abgelegt und mit git versioniert.

Um den Klassen individuell zusammengestellte Inhalte zu präsentieren, wird im material.config.yaml festgelegt, welche Inhalte welcher Klasse angezeigt werden. Das Standard-Format sieht wie folgt aus:

28Gj:
    - from: docs/OF-BYOD-Basics/
      to: versioned_docs/version-28Gb/01-BYOD
    - from: docs/OF-Word/
      to: versioned_docs/version-28Gb/03-Word
      ignore:
          - _category_.yml
29Ga:
    - from: docs/OF-BYOD-Basics-29/
      to: versioned_docs/version-29Ga/02-BYOD
      open: true

from

Pfad zum Quellordner oder der Quelldatei, die verteilt werden soll. Der Pfad ist relativ zum Projektstammverzeichnis.

to

Pfad zum Zielordner, in dem die Inhalte für die jeweilige Klasse abgelegt werden. Der Pfad ist relativ zum Projektstammverzeichnis.

ignore

optional

Liste von Dateien oder Ordnern, die nicht kopiert werden sollen. Der Pfad ist relativ zum Quellordner.

⚠️ aktuell können nur direkt im Quellordner liegende Dateien oder Ordner ignoriert werden. Unterordner werden nicht unterstützt.

open

optional

Gibt an, ob der Ordner in der Navigation standardmässig geöffnet sein soll. In diesem Fall wird ein Datei _category_.json im Zielordner erstellt, in dem die Einstellung gespeichert wird.

Obige Konfiguration kann auch abgekürzt wie folgt geschrieben werden:

28Gj:
    - material: OF-BYOD-Basics
      as: 01-BYOD
    - material: OF-Word
      as: 03-Word
      ignore:
          - _category_.yml
29Ga:
    - material: OF-BYOD-Basics-29
      as: 02-BYOD
      open: true

material

Pfad zum Quellordner, relativ zum Ordner /docs. Der Ordnername wird automatisch dem Pfad /docs vorangestellt.

as

Pfad zum Zielordner, relativ zum Ordner versioned_docs/version-<klasse>/.

alias section (kann gleichbedeutend zu as verwendet werden)

CLI

Um das Material entsprechend der Konfiguration im material.config.yaml in die jeweiligen Klassenordner zu kopieren, muss folgender Befehl ausgeführt werden:

yarn run sync

Scripts in package.json

Folgende Einträge können in der package.json hinzugefügt werden, um die Nutzung zu vereinfachen:

{
    "scripts": {
        "sync": "yarn workspace @tdev/material-sync sync",
        "remove": "yarn workspace @tdev/material-sync run remove",
        "postremove": "yarn workspace @tdev/material-sync sync",
        "precleanup": "yarn workspace @tdev/material-sync restore",
        "cleanup": "yarn workspace @tdev/material-sync cleanup",
        "addClass": "yarn workspace @tdev/material-sync run addClass",
        "add": "yarn workspace @tdev/material-sync run add",
        "postadd": "yarn workspace @tdev/material-sync sync"
    }
}

Zudem muss sichergestellt werden, dass die Dokumente vor einem Build synchronisiert werden - dies kann entweder in der CI/CD-Pipeline oder in einem Prebuild-Skript geschehen. Beispielsweise kann folgendes in der package.json hinzugefügt werden:

{
    "scripts": {
        "prebuild": "yarn workspace @tdev/material-sync sync"        
    }
}

Material Hinzufügen

Um die Inhalte für Klassen leichter zu konfigurieren, kann über die Kommandozeile wie folgt vorgegangen werden:

# add /OF-BYOD-Basics to 28Ga & 28Gb as /OF-BYOD-Basics
yarn run add docs/OF-BYOD-Basics/ --to="28Ga,28Gb"   
# add /OF-BYOD-Basics to 28Ga & 28Gb as /01-BYOD
yarn run add docs/OF-BYOD-Basics/ --to="28Ga,28Gb" --as="01-BYOD" 
# ignoriert _category_.json und alle .txt-Dateien im Quellordner
yarn run add docs/OF-BYOD-Basics/ --to="28Ga,28Gb" --as="01-BYOD" --ignore="_category_.json,*.txt"

Autovervollständigung von Pfaden

Bash ermöglich das Autovervollständigen von Pfaden und Dateinamen mit der tab-Taste. Dies kann beim Tippen von Pfaden sehr hilfreich sein.

Material synchronisieren

Das Material wird entsprechend der Konfiguration im material.config.yaml in die jeweiligen Klassenordner kopiert. Dies kann über die Kommandozeile wie folgt ausgeführt werden:

yarn run sync

[Dev] Material aufräumen

Um im Entwicklungsprozess die Aufstartzeit zu verkürzen, können die übers material.config.yaml konfigurierten Inhalte in den Klassenordnern gelöscht werden. Dies kann über die Kommandozeile wie folgt ausgeführt werden:

yarn run cleanup

Material aus der Konfiguration entfernen

Um Inhalte aus der Konfiguration zu entfernen, kann über die Kommandozeile wie folgt vorgegangen werden:

yarn run remove docs/OF-BYOD-Basics/ --from="28Ga,28Gb"

Alternativ können auch die entsprechenden Zeilen aus dem material.config.yaml gelöscht werden.

Neue Klasse hinzufügen

Um eine neue Klasse hinzuzufügen, kann über die Kommandozeile wie folgt vorgegangen werden:

yarn run addClass 30Ga

oder für mehrere Klassen gleichzeitig:

yarn run addClass 30Ga,30Gb,30Gc