Bookstack

Opensource Dokumentationsplattform.

Benutzung

Benutzung

Best Practice

Gruppierung von Inhalten

Inhalte bzw. Seiten sind grundsätzlich unabhängig vom Status ihrer Veröffentlichung im thematisch passenden Buch einzusortieren. Bücher dienen der Gruppierung von Inhalten, nicht, um Berechtigungen und Status der Veröffentlichung abzubilden. Seiten, die nur intern sichtbar sein sollen, sollen in einem Kapitel intern zusammengefasst werden.

Gliederung von Seiten

Textformatierung

Inhalte aus anderen Dokumenten übernehmen

Bei der Übernahme von Inhalten, insbesondere aus Word-, PDF-Dokumenten und Web-Seiten ist darauf zu achten, dass Inhalte ohne Formatierung übernommen werden. Nach dem Kopieren (Strg + C) sollen diese mit Strg + Shift + V eingefügt werden.

Werden Inhalte aus Mails oder PDFs übernommen, werden Zeilenumbrüche mit übernommen. Zeilenumbrüche müssen entfernt und durch ein Leerzeichen ersetzt werden, damit der Textfluss gegeben ist.

Aus der PDF:

Hallo. Ich bin ein kleiner Blindtext. Und zwar[Umbruch]
schon so lange ich denken kann. Es war nicht[Umbruch]
leicht zu verstehen, was es bedeutet, ein blinder[Umbruch]
Text zu sein: Man ergibt keinen Sinn.

In Bookstack:

Hallo. Ich bin ein kleiner Blindtext. Und zwar[Leerzeichen]schon so lange ich denken kann. Es war nicht[Leerzeichen]leicht zu verstehen, was es bedeutet, ein blinder[Leerzeichen]Text zu sein: Man ergibt keinen Sinn.

Zudem sind vor und nach Überschriften keine Leerzeilen einzufügen:

Überschrift
[Leerzeile]
Hallo. Ich bin ein kleiner Blindtext.
[Leerzeile]
[Bild]
[Leerzeile]

Überschrift
Hallo. Ich bin ein kleiner Blindtext.
[Bild]

Verlinkungen

Anmerkungsfelder und Inline Code

Achtung: Wird verwendet, um besonders wichtige Sachverhalte darzustellen

Tipp: Wird verwendet, um besonders hilfreiche Tipps darzustellen

Information: Wird verwendet, um zusätzliche Hinweise darzustellen

Wird im Text beschrieben, dass ein Button o. ä. angeklickt werden soll, dann diesen mit dem Inline Code kennzeichnen:

Im Tab Bewertung sehen Sie die Bewertungen. Klicken Sie auf Speichern und beenden. (Strg + 8)

Formulierungen

Anleitungen

Bilder

Bilder können per Drag and Drop auf die Seite, mit Strg + v aus der Zwischenablage oder über den integrierten Zeichnungseditor eingefügt werden. Die letzten beiden Wege erzeugen PNGs. Bilder sollten

Dateiformat

Bilder können im JPEG- und PNG-Format eingefügt werden. Um die bestmögliche Bildqualität bei gleichzeitig geringer Dateigröße zu erzielen, sollte das passende Format gewählte werden:

Als JPEG gespeicherte Screenshots können Artefakte (unscharfe Kanten) enthalten, während bei im PNG-Format gespeicherten natürlichen Fotos Flächenbildung und Verfärbungen entstehen.

Formatierung

Screenshot beschriften und einfügen

Manchmal müssen in einem Screenshot Elemente hervorgehoben werden. Dazu wie folgt vorgehen:

  1. Screenshot erstellen, in Zwischenablage speichern
  2. Bildvorlage durch Doppelklick mit integrierten Editor öffnen
  3. Screenshot mit Strg + v aus der Zwischenablage einfügen
  4. Bilder nicht skalieren, da sie sonst unscharf werden
  5. gewünschte Stellen markieren, dazu vorhandene Elemente (Rahmen, Pfeile, Badges) duplizieren und auf Screenshot legen; Grundsätzlich sollte für alle Markierungen nur eine Farbe verwendet werden, üblicherweise sollte dies das Rot sein. Falls das wegen des Hintergrundes nicht passt, ist eine der Farben in folgender, absteigender Priorität zu verwendenden:
    1. Rot (Granat, #b02f2c bzw.  RGB 176, 47, 44)
    2. Schwarz (Basalt, #262a31 bzw. RGB 38, 42, 49)
    3. Weiß (#ffffff bzw. RGB 255, 255, 255)
    4. Blau (Aquamarin, #8ac2d1 bzw. RGB 138, 194, 209)
  6. Anzeigegröße auf 100 % stellen

    image.png

  7. Den mit Markierungen überlagerten Screenshot im Editor erneut screenshoten
  8. Screenshot mit Strg + v in Seite einfügen
  9. falls notwendig, Anzeigegröße im Rastermaß von 150 px verringern

    image.png

  10. Bildvorlage nicht speichern

Alternativtexte

Die. o. g. Punkte sind eine Zusammenfassung der Präsentation "Gute Alternativtexte schreiben" von Manu Heim der ETH Zürich.

Bei Unklarheit hier im Quellcode das unterste Bild anschauen. Im Quellcode lässt sich auch der Alternativtext von JPEGs anpassen.

Zeichnungseditor

Der integrierte Editor bietet die Möglichkeit, Zeichnungen zu erstellen. Das Ergebnisbild wird als PNG gespeichert uns ist später wieder bearbeitbar. Er hat folgende Vorteile:

Er hat aber auch folgende Nachteile gegenüber klassisch eingefügten Bildern:

  1. Screenshot oder Bilder sollen mit dem Button Zeichnung einfügen/bearbeiten bearbeitet werden:

Icons

🔗 https://www.urz.uni-leipzig.de/servicedesk-und-hilfe/kontakt-zum-servicedesk
📧 servicedesk@uni-leipzig.de
☎ +49 341 97-33333

▶️ Referat vs. Erklärfilm

Icons sind nur in Ausnahmefällen zu verwenden.

Anhänge

Inhalte sollten nativ, d. h. direkt mit dem vorhandenen Editor, eingepflegt werden. Die Verwendung von Anhängen ist nicht zu empfehlen. Anhänge

Benutzung

Formatierung

Text

Formatierung Tastenkombination für Windows
 Tastenkombination für Mac
Fett Strg + B ⌘ + b
kursiv Strg + I ⌘ + i
unterstrichen Strg + U

⌘ + u
Best Practice mit Bookstack (intern) Strg + Shift + K ⌘ + ⇧ + k
Universität Leipzig (extern) Strg + K
Inline Code Strg + 8
 ⌘ + ⇧ + e
ohne Formatierung einfügen
 Strg + Shift + v
 ⌘ + ⇧ + ⌥ + v

Große Überschrift (Strg + 1)

Mittlere Überschrift (Strg +2)

Kleine Überschrift (Strg + 3)

Sehr kleine Überschrift (Strg + 4)

Anmerkungen und Zitate

(1x Strg + 9) zusätzliche Information

(2x Strg + 9) hilfreiche Tipps

(3x Strg + 9) Warnung

(4x Strg + 9) besonders wichtige Sachverhalte

Zitate erstellt man mit Strg + 6

Damit kann man Skripte und Code mit automatischer Formatierung darstellen, damit der Code besser lesbar ist:

{
    "_comment:" "Code Highlighting mit Strg + 7",
    "Code:" "JSON",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "age": 45,
    "weight": 67,
    "admin": true
}

Listen und Nummerierungen

Unsortierte Liste (Strg + P)

Sortierte Liste (Strg + O)

  1. Chef
  2. Abteilungsleiter
  3. Teamleiter
  4. Mitarbeiter

Tabellen

Sie eignen sich zur strukturierten Darstellung, sind jedoch insbesondere für die Darstellung auf mobilen Geräten ungeeignet und sollten daher vermieden werden.

grammatische Personen

Singular Plural
1. Person ich wir
2. Person du ihr
3. Person er, sie, es sie

Bilder/Grafiken/Zeichnungen

Entscheidungsbaum über die Einrichtungsstruktur der UL

Benutzung

Begriffe und Formulierungen

Die "Wie wird das nochmal geschrieben?"-Liste

Benutzung

Inhalte wiederverwenden

Arbeiten mit ID-Seiten

ID-Seiten beinhalten Informationen, Texte, Bilder, die per Einbettung auf beliebig vielen Seiten genutzt werden können. Der Inhalt muss dabei nur auf der einen ID-Seite aktualisiert werden.

Eine englische Erklärung dazu befindet sich hier: Reusing Page Content · BookStack.

Eine ID-Seite muss eine öffentlich sichtbare Seite sein. Für die Einbettung der Seite oder eines Abschnittes wird der entsprechende Teil bzw. markiert und in dem Pop-up-Menü auf das Link-Symbol. Es wird ein Einbettungscode generiert.

Die Einbettung funktioniert nicht bei Aufzählungszeichen! Will man die originale ID-Seite finden, fügt man die ID-Nummer in die URL ein: https://kb.el.uni-leipzig.de/link/xxx

Dieser Code wird auf der Seite, wo der Inhalt eingefügt werden soll, hineinkopiert.
Beispiel zur Einbettung des EL-Kontaktes:

Support

📧 servicedesk@uni-leipzig.de
☎ +49 341 97-33333
Mo - Do 9 - 16 Uhr
Fr            9 - 14 Uhr
🔗 Servicedesk

📧 elearning@uni-leipzig.de
☎ +49 341 97-33334
Mo - Do 9 - 15 Uhr
Fr            9 - 14 Uhr

Seiten als Vorlage

Eine erstellte Seite kann als Vorlage für weitere neue Seiten genutzt werden. Bei der erstellten Seite klickt man rechts oben auf das Icon Vorlagen.

Möchte man die geöffnete Seite als Vorlage sichern, setzt man den Haken bei Seite ist eine Vorlage. Soll hingegen diese geöffnete Seite mit einer Vorlage gestaltet werden, sucht man darunter die entsprechende Vorlage.

Wird eine Vorlage genutzt, werden bereits erstellte Inhalte auf der Seite gelöscht!

Administration

Administration

Bookstack Dokumentation

https://www.bookstackapp.com/docs/admin/

Fehlersuche im System:

https://www.bookstackapp.com/docs/admin/debugging/

Administration

Backup

Dieses Skript sichert die Datenbank und alle Benutzerdateien. Siehe auch

https://www.bookstackapp.com/docs/admin/backup-restore

Skript

#!/bin/bash
#set -x
BACKUPDIR=/backup/bookstack
MYSQL_DB=bookstack
WWW_DIR=/var/www/bookstack
ITEMS=".env public/uploads/ storage/uploads/ themes/"

MINFILESIZE=200 # in kb
KEEP=28 # in days
EMAIL="[Absender]"

DATE=$(date "+%Y-%m-%dT%H%M%S%z")
FILENAME=${BACKUPDIR}/$MYSQL_DB-$DATE.sql

mysqldump --triggers --routines $MYSQL_DB -r $FILENAME
DB_DUMPSIZE=$(du -k $FILENAME|cut -f1)
if [[ -r $FILENAME && $DB_DUMPSIZE -ge $MINFILESIZE ]]
then
  xz -9e --lzma2=dict=1024MiB,nice=273 $FILENAME
else
  echo -e "Host:\t\t\t$(hostname -f)\nDB:\t\t\t$MYSQL_DB\nDatei:\t\t\t$FILENAME\nGröße (min):\t\t$MINFILESIZE kb\nGröße (tatsächlich):\t$DB_DUMPSIZE kb"|mailx -s "Backup gescheitert: $MYSQL_DB" $EMAIL
fi

FILENAME_ARCHIVE=${BACKUPDIR}/$(basename $WWW_DIR)-$DATE.tar.xz
tar --exclude=storage/framework -cf $FILENAME_ARCHIVE --use-compress-program='xz -9 --lzma2=dict=1024MiB,nice=273' -C /${WWW_DIR} $ITEMS

find $BACKUPDIR/* -type f -mtime +$KEEP -exec rm {} \; 2>&1

Cronjob

15 3 * * 2-6 /usr/local/bin/bs-backup-db.sh

Administration

Suchmaschinenoptimierung

Sitemap

Um Suchmaschinen die Indizierung Inhalte von Bookstack zu erleichtern, wird mittels eines Skriptes eine Sitemap generiert.

Installation

Cronjob

15 3 * * 2-6 /usr/local/bin/bs-backup.sh

Anmeldung zur Indizierung

Die Website inkl. Sitemap bei Suchmaschinen anmelden

Administration

Optimierung von Bilddateien

Im Wesentlichen werden zwei Bildformate verwendet, wobei jedes Format für bestimmte Inhalte optimiert ist:

Meist werden diese Bilder nicht im für Webseiten optimalen Format gespeichert, d. h.

Hier einige Referenzen zur Optimierung von Bildern für die Darstellung auf Webseiten:

Bilder in Bookstack automatisch optimieren

Um Nutzer nicht unnötig mit der Optimierung zu belasten, optimiert nachfolgendes Skript Bilddateien automatisch. Dabei kommen pngquant und jpegoptim zum Einsatz, welche für gängige Linux-Distributionen angeboten werden. Täglich 1x werden die Bilder aller Unterverzeichnisse (cover_book, cover_bookshelf, drawio, gallery, system, user) des aktuellen Monats im Image-Ordner bearbeitet.

Verzeichnis: /var/www/bookstack/public/uploads/images/[asset]/[YYYY-MM]/

Mit jedem Durchlauf werden Bilder weiter optimiert, wobei die Optimierung beim ersten Durchlauf am größten ist. Pngquant und jpegoptim optimieren die Bilder nur, wenn eine Mindestqualität nicht unterschritten wird. Die mehrfache Anwendung des Skriptes verschlechtert die Bildqualität daher nicht. Nach 2 bis 3 Durchläufen ist das angestrebte Optimum erreicht. In Tests mit mehreren hundert Bildern wurden zwischen 66 und 80 % der Dateigröße ohne sichtbaren Qualitätsverlust eingespart. Bei Dateien die mit in Bookstack integriertem draw.io erstellt/bearbeitet wurden und welche im Ordner drawio liegen, werden die Metadaten beibehalten, da diese die Vektorgrafiken für spätere Bearbeitung enthalten. Würden sie entfernt, könnten sie nicht mehr mit draw.io bearbeitet werden.

Benötigte Komponenten installieren:

apt-get update
apt-get install pngquant
apt-get install jpegoptim

Skript installieren

/usr/local/bin/bs-opt-img.sh

# !/bin/bash
# set -x
#
# Recompresses uploaded images of the current month and strips meta tags.
# Images are only processed if there are potential savings. Script can be run
# multiple times without recompressing already compressed images - processed
# images are skipped.Needs pngqunat and jpegoptimum to be installed. Run script
# atleast once a week better daily.
# Logs at /var/log/[script-name].log
# Metadata of png files in drawio are not stripped because they are containing
# vector data which are neccessary to edit these drawings
#
# Version 2023-10-25
# daniel.obst@uni-leipzig.de

FOLDER_BASE=/var/www/bookstack/public/uploads/images

LOG=/var/log/`echo $(basename "$0") | rev | cut -d. -f2- | rev`.log
#FOLDERS="cover_book cover_bookshelf drawio gallery system user"
echo "$(date '+%Y-%m-%d %H:%M:%S') === START ===" >> $LOG
FOLDERS="`ls -q $FOLDER_BASE`"
for FOLDER in $FOLDERS; do
  FOLDER_LONG=$FOLDER_BASE/$FOLDER/`date +"%Y-%m"`/
# FOLDER_LONG=$FOLDER_BASE/$i/2023-07/
  if [ -d "$FOLDER_LONG" ]; then
    DU_BEFORE=`du -s --block-size=1 $FOLDER_LONG | cut -f1`
    DU_BEFORE_K=$(($DU_BEFORE/1024))
    FILES=`ls  -lq $FOLDER_LONG | grep -iE ".*\.(jpg|jpeg|png)$" | wc -l`
    if [ $FILES -gt 0 ]; then
      if [ "$FOLDER" = "drawio" ]; then
        find $FOLDER_LONG -name "*.png" -exec pngquant --force --skip-if-larger --speed=1 --ext .png --quality=60-80 {} \;
        find $FOLDER_LONG -name "*.PNG" -exec pngquant --force --skip-if-larger --speed=1 --ext .PNG --quality=60-80 {} \;
      else
        find $FOLDER_LONG -name "*.png" -exec pngquant --strip --force --skip-if-larger --speed=1 --ext .png --quality=60-80 {} \;
        find $FOLDER_LONG -name "*.PNG" -exec pngquant --strip --force --skip-if-larger --speed=1 --ext .PNG --quality=60-80 {} \;
      fi
      find $FOLDER_LONG -iname "*.png" -exec chown -f --reference=$FOLDER_LONG {} \;
      find $FOLDER_LONG -iregex ".*\.jpe?g" -exec jpegoptim -q -p --all-progressive -m75 --strip-com --strip-exif --strip-iptc --strip-icc --strip-xmp {} \;
      DU_AFTER=`du -s --block-size=1 $FOLDER_LONG | cut -f1`
      DU_AFTER_K=$((DU_AFTER/1024))
      if [ $DU_AFTER -lt $DU_BEFORE ]; then
        SAVED_K=$((DU_BEFORE_K-$DU_AFTER_K))
        echo "$(date '+%Y-%m-%d %H:%M:%S') $FOLDER_LONG $FILES images, folder shrinked from ${DU_BEFORE_K}k to ${DU_AFTER_K}k, ${SAVED_K}k saved" >> $LOG
      else
        echo "$(date '+%Y-%m-%d %H:%M:%S') $FOLDER_LONG nothing to do, $FILES images, ${DU_AFTER_K}k" >> $LOG
     fi
    else
      echo "$(date '+%Y-%m-%d %H:%M:%S') $FOLDER_LONG no images found" >> $LOG
    fi
  else
    echo "$(date '+%Y-%m-%d %H:%M:%S') $FOLDER_LONG does not exists" >> $LOG
  fi
done
echo "$(date '+%Y-%m-%d %H:%M:%S') $FOLDER_BASE/ `find $FOLDER_BASE/. -type f | wc -l` files, `du -sh $FOLDER_BASE | cut -f1`" >> $LOG
echo "$(date '+%Y-%m-%d %H:%M:%S') === STOP ===" >> $LOG

Cronjob

mit crontab -e

0 23 * * * /usr/local/bin/bs-opt-img.sh

Logs

Das Skript schreibt Logs nach /var/log/bs-opt-img.log. Um zu verhindern, dass die Logs die Festplatte vollschreiben, sollten die Logs rotiert werden. Dazu eine Datei /etc/logrotate.d/bs-opt-img mit folgendem Inhalt anlegen:

/var/log/bs-opt-img.log
{
        rotate 4
        weekly
        missingok
        notifempty
        compress
        delaycompress
        sharedscripts
}

Syslog Daemon neustarten:

systemctl restart rsyslog.service
Administration

überflüssige Bilder löschen

Nachfolgendes Skript löscht Bilder, die nicht mehr referenziert sind:

Skript

/usr/local/bin/bs-cleanup-img.sh:

# !/bin/bash
# set -x
#
# Cleanup images and drawings
# Also delete images that are only used in old revisions
# depending on amount of images cleanup will take several minutes
#
# Version 2024-02-29

APP_FOLDER=/var/www/bookstack
IMG_FOLDER=${APP_FOLDER}/public/uploads/images
LOG=/var/log/`echo $(basename "$0") | rev | cut -d. -f2- | rev`.log

echo "$(date '+%Y-%m-%d %H:%M:%S') === START ===" >> $LOG
echo "working on ${APP_FOLDER}" >> $LOG
DU_BEFORE=`du -s --block-size=1 $IMG_FOLDER | cut -f1`
DU_BEFORE_K=$(($DU_BEFORE/1024))
FILES_BEFORE=`ls -lqR ${IMG_FOLDER} | grep -iE ".*\.(jpg|jpeg|png)$" | wc -l`

php ${APP_FOLDER}/artisan bookstack:cleanup-images -f -n -v >> $LOG

DU_AFTER=`du -s --block-size=1 $IMG_FOLDER | cut -f1`
DU_AFTER_K=$(($DU_AFTER/1024))
FILES_AFTER=`ls -lqR ${IMG_FOLDER} | grep -iE ".*\.(jpg|jpeg|png)$" | wc -l`

if [ $DU_AFTER -lt $DU_BEFORE ]; then
  DELETED_K=$((DU_BEFORE_K-$DU_AFTER_K))
  FILES_DELETED=$((FILES_BEFORE-$FILES_AFTER))
  echo "${FILES_BEFORE} - ${FILES_AFTER} = ${FILES_DELETED} deleted" >> $LOG
  echo "${DU_BEFORE_K} - ${DU_AFTER_K} = ${DELETED_K}k deleted" >> $LOG
else
  echo "nothing to do, ${FILES_AFTER} files, ${DU_AFTER_K}k" >> $LOG
fi
echo "$(date '+%Y-%m-%d %H:%M:%S') === STOP ===" >> $LOG

Auszug aus dem Log:

2024-02-29 16:31:19 === START ===
working on /var/www/bookstack
This operation is destructive and is not guaranteed to be fully accurate.
Ensure you have a backup of your images.

Image(s) to delete:
/uploads/images/gallery/2023-07/img-20220630-132119.jpg
/uploads/images/gallery/2023-08/PGBimage.png
[..]
/uploads/images/gallery/2024-01/vRZgrafik.png
/uploads/images/drawio/2024-02/drawing-7-1706817605.png
/uploads/images/drawio/2024-02/drawing-21-1708611127.png
325 image(s) deleted
8934 - 8000 = 934 files deleted
315784k - 256552k = 59232k deleted
2024-02-29 16:32:37 === STOP ===
2024-02-29 17:09:58 === START ===
working on /var/www/bookstack
This operation is destructive and is not guaranteed to be fully accurate.
Ensure you have a backup of your images.

0 image(s) deleted
nothing to do, 8000 files, 256552k
2024-02-29 17:24:18 === STOP ===

Cronjob

Skript sonntags 3:15 Uhr ausführen:

15 3 * * 7 /usr/local/bin/bs-cleanup-img.sh

Logrotate

/etc/logrotate.d/bs-cleanup-img

/var/log/bs-cleanup-img.log
{
        rotate 4
        weekly
        missingok
        notifempty
        compress
        delaycompress
        sharedscripts
}

Service neustarten, um Konfig zu aktivieren

systemctl restart rsyslog.service