Improve custom fonts handling, document it

Closes #158 - Allow custom fonts for resources, document how to use them

.env.docker

@@ -21,9 +21,9 @@
 TEKST_SERVER_URL=http://127.0.0.1:8087
 TEKST_WEB_PATH=/
 TEKST_API_PATH=/api
+TEKST_WEB_STATIC_FILES=/var/www/tekst/static/
 
 # TEKST_LOG_LEVEL=warning
-# TEKST_USER_FILES_DIR=userfiles
 
 # TEKST_CORS_ALLOW_ORIGINS=*
 # TEKST_CORS_ALLOW_CREDENTIALS=true

Tekst-API/.env

@@ -23,7 +23,6 @@
 # TEKST_API_PATH=/api
 
 # TEKST_LOG_LEVEL=warning
-# TEKST_USER_FILES_DIR=userfiles
 
 # TEKST_SETTINGS_CACHE_TTL=60
 

Tekst-API/dev/caddy/Caddyfile

@@ -0,0 +1,14 @@
+127.0.0.1:80 {
+	redir /api /api/
+	handle_path /api/* {
+		reverse_proxy 127.0.0.1:8000
+	}
+
+	handle_path /static/* {
+		encode gzip
+		root * /var/www/tekst/static
+		file_server
+	}
+
+	reverse_proxy * 127.0.0.1:5173
+}

Tekst-API/dev/docker-compose.yml

@@ -4,7 +4,8 @@ services:
   caddy:
     image: "caddy:2.6-alpine"
     volumes:
-      - "./:/etc/caddy/:ro"
+      - "./caddy:/etc/caddy/:ro"
+      - "./static:/var/www/tekst/static/:ro"
     network_mode: "host"
     profiles:
       - dev

Tekst-API/dev/static/fonts.css

@@ -0,0 +1,22 @@
+/*
+
+DEFINE ADDITIONAL FONT FAMILIES HERE IN THIS FILE.
+PLEASE MAKE SURE THE PUBLIC PATH TO THE FONT FILES IS CORRECT. YOU SHOULD PLACE YOUR
+FONT FILES IN <WEB_STATIC_FILES>/FONTS/ AND REFERENCE THEM VIA THE PUBLIC PATH
+/static/fonts/... LIKE BELOW:
+
+@font-face {
+  font-family: 'Noto Serif';
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url('/fonts/Noto-Serif/Noto-Serif-Regular.eot');
+  src:
+    url('/static/fonts/Noto-Serif/Noto-Serif-Regular.eot?#iefix') format('embedded-opentype'),
+    url('/static/fonts/Noto-Serif/Noto-Serif-Regular.woff2') format('woff2'),
+    url('/static/fonts/Noto-Serif/Noto-Serif-Regular.woff') format('woff'),
+    url('/static/fonts/Noto-Serif/Noto-Serif-Regular.ttf') format('truetype'),
+    url('/static/fonts/Noto-Serif/Noto-Serif-Regular.svg#NotoSerif') format('svg');
+}
+
+*/

Tekst-API/dev/static/fonts/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

Tekst-API/tekst/config.py

@@ -6,7 +6,13 @@
 from urllib.parse import quote
 
 from fastapi import Depends
-from pydantic import EmailStr, Field, StringConstraints, computed_field, field_validator
+from pydantic import (
+    EmailStr,
+    Field,
+    StringConstraints,
+    computed_field,
+    field_validator,
+)
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from tekst import pkg_meta
@@ -76,7 +82,6 @@ class TekstConfig(BaseSettings):
     api_path: str = "/api"
 
     log_level: str = "warning"
-    user_files_dir: str = "userfiles"
 
     settings_cache_ttl: int = 60
 

Tekst-Web/Dockerfile

@@ -1,26 +1,37 @@
+# =======
+# BUILDER
+# =======
+
 FROM node:18.15-alpine AS builder
 
 ARG WEB_PATH
 ARG SERVER_URL
 ARG API_PATH
-
 ENV TEKST_SERVER_URL=$SERVER_URL \
     TEKST_API_PATH=$API_PATH
 
-WORKDIR "/app"
+WORKDIR /app
 COPY . .
 RUN npm install && npm run build -- --base=$WEB_PATH
 
 
+# =================
+# PROD CLIENT IMAGE
+# =================
+
 FROM caddy:2.6-alpine AS prod
 
 ARG API_PATH
 ENV TEKST_API_PATH=$API_PATH
 
-WORKDIR "/var/www/html"
+WORKDIR /var/www/html
 COPY --from=builder /app/dist/ ./
 COPY ./deploy/Caddyfile /etc/caddy/
+
+VOLUME /var/www/tekst/static
+
 # 82:82 is alpine default for www-data
 RUN set -x && adduser -u 82 -D -S -G www-data www-data
 USER www-data
+
 EXPOSE 80

Tekst-Web/deploy/Caddyfile

@@ -6,11 +6,16 @@
 :80 {
 	redir {$TEKST_API_PATH:/api} {$TEKST_API_PATH:/api}/
 
-	handle {$TEKST_API_PATH:/api}/* {
-		uri strip_prefix {$TEKST_API_PATH:/api}
+	handle_path {$TEKST_API_PATH:/api}/* {
 		reverse_proxy http://server:8000
 	}
 
+	handle_path /static/* {
+        encode gzip
+		root * /var/www/tekst/static
+		file_server
+	}
+
 	handle * {
 		try_files {path} /
 		encode gzip

Tekst-Web/index.html

@@ -12,6 +12,7 @@
     <meta name="naive-ui-style" />
     <link href="/fonts.css" rel="stylesheet" />
     <link href="/base.css" rel="stylesheet" />
+    <link href="/static/fonts.css" rel="stylesheet" />
   </head>
 
   <body>

Tekst-Web/public/fonts.css

@@ -1,17 +1,3 @@
-/*
-
-  CUSTOM FONT DEFINITIONS GO HERE!
-  FOR AN EXAMPLE, SEE THE DEFAULT FONT DEFINITIONS AT THE END OF THIS FILE!
-
-*/
-
-/*
-
-  THE FONT DEFINITIONS BELOW SHOULD NOT BE CHANGED,
-  AS THESE FONTS ARE USED AS DEFAULTS/FALLBACKS IN THE APPLICATION
-
-*/
-
 @font-face {
   font-family: 'Tekst UI Font';
   font-style: normal;

Tekst-Web/src/components/navigation/PrimaryNavBar.vue

@@ -34,11 +34,11 @@ const customLogoError = ref(false);
 const logoPath = computed(() =>
   customLogoError.value
     ? theme.darkMode
-      ? '/tekst-logo-darkmode.png'
-      : '/tekst-logo.png'
-    : theme.darkMode
       ? '/logo-darkmode.png'
       : '/logo.png'
+    : theme.darkMode
+      ? '/static/logo-darkmode.png'
+      : '/static/logo.png'
 );
 
 const titleLinkTo = computed(() => {

Tekst-Web/src/views/admin/AdminSystemSettingsView.vue

@@ -331,8 +331,11 @@ function resetForm() {
 
       <n-divider />
 
-      <!-- RESOURCE CATEGORIES-->
-      <h3>{{ $t('models.platformSettings.resourceFonts') }}</h3>
+      <!-- RESOURCE FONTS-->
+      <icon-heading level="3">
+        {{ $t('models.platformSettings.resourceFonts') }}
+        <help-button-widget help-key="adminSystemSettingsResourceFonts" />
+      </icon-heading>
       <n-form-item v-if="formModel.resourceFonts" :show-label="false">
         <n-dynamic-input
           v-model:value="formModel.resourceFonts"

Tekst-Web/translations/help/deDE/adminSystemSettingsResourceFonts.md

@@ -0,0 +1,5 @@
+# Individuelle Ressourcen-Schriftarten
+
+Sie können sich und anderen Benutzern die Möglichkeit geben, alternative Schriftarten für bestimmte Ressourcen zu verwenden. Dies kann etwa dann sinnvoll sein, wenn die Inhalte einer Ressource einen bestimmten Zeichensatz oder Diakritika verwenden, die durch die Standard-Schriftart für Inhalte nicht dargestellt werden können.
+
+Bitte entnehmen Sie dem Kapitel "Advanced Setup" der Dokumentation, wie zusätzliche Schriftarten eingerichtet werden können.

Tekst-Web/translations/help/enUS/adminSystemSettingsResourceFonts.md

@@ -0,0 +1,5 @@
+# Custom Resource Fonts
+
+You can provide yourself and other users with the option to use alternative fonts for specific resources. This can be useful when the content of a resource uses a specific character set or diacritics that cannot be displayed by the default font for content.
+
+Please refer to the advanced setup guide in the main documentation to learn how to do this.

Tekst-Web/translations/ui/enUS.yml

@@ -256,12 +256,12 @@ models:
     navInfoEntry: Custom label for info entry in main navigation
     alwaysShowTextInfo: Show text info and selector in header even on non-text-specific pages
     showTekstFooterHint: Show a small hint to the Tekst software in the footer (Thank you!)
-    resourceCategories: Resource categories
+    resourceCategories: Resource Categories
     resourceCategoryKey: Key
     resourceCategoryTranslation: Label
     showResourceCategoryHeadings: Show resource category headings in browse view
     alwaysShowResourceCategoryHeadings: Show resource category headings even for the only category with resources
-    resourceFonts: Custom resource fonts
+    resourceFonts: Custom Resource Fonts
     resourceFontName: Name
   segment:
     modelLabel: Segment

docker-compose.yml

@@ -17,6 +17,8 @@ services:
     environment:
       TEKST_SERVER_URL: ${TEKST_SERVER_URL}
       TEKST_API_PATH: ${TEKST_API_PATH}
+    volumes:
+      - ${TEKST_WEB_STATIC_FILES}:/var/www/tekst/static/:ro
     restart: always
     init: true
     ports:

docs/content/setup-advanced.md

@@ -0,0 +1,22 @@
+# Advanced Setup
+
+## Custom Resource Fonts
+
+You can provide yourself and other users with the option to use alternative fonts for specific resources. This can be useful when the content of a resource uses a specific character set or diacritics that cannot be displayed by the default font for content.
+
+To add additional fonts for resources, you need administrative access to the server on which the platform application is deployed. The setup of additional fonts is precisely described below. It is always recommended to create a backup of all application data before performing these steps.
+
+### Deployment with Docker
+
+1. In the `.env` file, set the value for `TEKST_WEB_STATIC_FILES` to a path under which you want to make additional static files available for the web client (e.g., `/var/www/tekst/static/`) and create the corresponding directories.
+2. Create a file `fonts.css` under this path.
+3. Also, create a folder `fonts` under this path, where you can store the additional fonts (possibly sorted into further subfolders). It is recommended to prepare each font in different formats optimized for web use (see also [here](https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts)!). Also, pay attention to the licensing of the fonts used and, if necessary, include the corresponding license file with the files.
+4. In the previously created `fonts.css`, create a complete `@font-face` definition for each of your fonts. See [here](https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts) again for details. As the public path to the files, specify `/static/fonts/<...>`, replacing `<...>` with the path within your previously created `fonts` folder.
+5. For the application to recognize the changed value in `.env`, it needs to be restarted (`docker-compose restart client`).
+6. The value used for `font-family` in the `@font-face` definition can now be entered as an additional font in the platform's system settings. Pay attention to identical spelling! This font can now be selected as a different font in the settings for each text-based resource.
+
+### Deployment without Docker
+
+1. Create a directory where you want to make additional static files available for the web client (e.g., `/var/www/tekst/static/`).
+2. Ensure that your web server makes this directory available as `/static` at the same address as the application, for example, `www.tekst-platform.org/static`.
+3. Follow steps 2 to 4, and 6 from the _Deployment with Docker_ instructions (see above).

docs/generated/help/adminSystemSettingsResourceFonts.md

@@ -0,0 +1,5 @@
+# Custom Resource Fonts
+
+You can provide yourself and other users with the option to use alternative fonts for specific resources. This can be useful when the content of a resource uses a specific character set or diacritics that cannot be displayed by the default font for content.
+
+Please refer to the advanced setup guide in the main documentation to learn how to do this.

docs/mkdocs.yml

@@ -8,6 +8,7 @@ nav:
   - 'index.md'
   - 'concepts.md'
   - 'setup.md'
+  - 'setup-advanced.md'
   - Usage:
     - 'Resources': 'usage/resources.md'