wikijs-metabot/README.md

# WikiJs Metabot

Ein Skript was die Page-Listings auf [https://wiki.ctdo.de](https://wiki.ctdo.de)
automatisch aktuell hält

## Verwendung

Um auf einer Wiki-Seite ein Page-Listing hinzuzufügen muss der Seite das `metapage`-Tag hinzugefügt
werden und an der gewünschten Stelle ein Kommentar folgender Form eingefügt werden:

```text
<!-- \pagelist QUERY -->
```

Dabei muss `QUERY` eine Parameterlist für die `PageQuery::list`-Methode der WikiJs-GraphQL-API sein.
Folgende Parameter werden unterstützt:

```text
limit: Int
orderBy: Enum CREATED | ID | PATH | TITLE | UPDATED
orderByDirection: Enum ASC | DESC
tags: [String]
locale: String
creatorId: Int
authorId: Int
```

### Beispiele

Liste aller Seiten die mit den Tags `top` und `new` versehen sind:

```text
<!-- \pagelist tags: ["top", "new"] -->
```

Liste der 10 zuletzt bearbeiteten Seiten:

```text
<!-- \pagelist orderBy: UPDATED, orderByDirection: DESC, limit: 10 -->
```

### Details

- Mehrere Parameter müssen mit einem Komma getrennt werden
- Mehrere Tags im `tags`-Parameter müssen ebenfalls mit Komma getrennt werden
- Parameter vom Typ `String` müssen in doppelte Anführungszeichen `"` eingeschlossen werden
- Parameter vom Typ `Int` und vom Typ `Enum` müssen ohne Anführungszeichen angegeben werden

## Features und Einschränkungen

Zur Rekursionsvermeidung können leider die mit `metapage` getaggten Seiten nicht selbst in den
Page-Listings auftauchen.
Eine Seite welche die zuletzt aktualisierten Seiten enthält, kann also nur Seiten enthalten welche
nicht mit `metapage` getaggt sind.

Seiten deren Pfad mit einem Unterstrich `_` beginnt werden als versteckt interpretiert und nicht in
Page-Listings angezeigt.
Das wird beispielsweise auf der Topictreff-Seite verwendet damit das Topic-Template nicht unter den
neuen Topics aufgelistet wird.

Bei gesetzten Limits kommt es vor, dass weniger Seiten als angegeben aufgelistet werden.
Das liegt daran, dass das Filtern zur Rekursionsvermeidung und zum verstecken von Seiten erst nach
dem Ausführen der GraphQL-Query passiert.
Außerdem scheint auch das WikiJs einen ähnlichen Bug zu haben wodurch manche Seiten nicht in dem
Ergebnis zurückgegeben aber trotzdem gezählt werden.

## Ausführen des Bots

Damit der Bot Seiten bearbeiten darf muss die Umgebungsvariable `CTDO_WIKIJS_API_KEY` auf einen
gültigen Api-Key gesetzt sein.
Api-Keys für das WikiJs können hier generiert werden: [https://wiki.ctdo.de/a/api](https://wiki.ctdo.de/a/api).

### Docker commands

Docker Container für den Bot bauen:

```sh
docker build -t wikijs-metabot .
```

Docker container ausführen:

```sh
docker run -it -e CTDO_WIKIJS_API_KEY wikijs-metabot
```