Migrate Documentation to Zensical

Fixes #1664

Author: bkis

.github/workflows/docs.yml

@@ -1,4 +1,4 @@
-name: Deploy docs
+name: Deploy documentation
 
 on:
   push:
@@ -11,26 +11,31 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: write
 
 jobs:
   deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     defaults:
       run:
         working-directory: ./docs
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: actions/configure-pages@v5
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v5
-        with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
-      - run: pip install mkdocs-material=="9.*" mkdocs-include-markdown-plugin=="7.*"
+          python-version: 3.x
       - run: sudo mkdir /includes && sudo cp ../Tekst-Web/i18n/help/enUS/** /includes/
-      - run: mkdocs gh-deploy --force
+      - run: pip install zensical
+      - run: zensical build --clean
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

CONTRIBUTING.md

@@ -1,5 +1,5 @@
 # Contributing
 
-Tekst is explicitly meant as an Open Source project that is open for community contributions. You are welcome to open Pull Requests with bug fixes or feature implementations.
+Tekst is explicitly meant as an Open Source project and is thus open for community contributions. You are welcome to open Pull Requests with bug fixes or feature implementations.
 
-That being said, to keep you from doing superfluous work, please [open an issue](https://github.com/VedaWebProject/Tekst/issues) describing a bug or feature idea and discuss the matter with a project maintainer before you start working on things ♥
+That being said, to keep you from doing superfluous work, please [open an issue](https://github.com/VedaWebProject/Tekst/issues) first and describe a bug or feature idea to discuss the matter with a project maintainer before you start working on things ♥

README.md

@@ -41,13 +41,13 @@ This is a monorepo containing the codebases of all parts of the Tekst platform.
 ### Projects and technologies
 
 #### Tekst-API
-The server part of the Tekst platform: [`Tekst-API/`](Tekst-API) \
+The server part of the Tekst platform, located in [`Tekst-API/`](Tekst-API). \
 [Python](https://github.com/python/cpython), [Pydantic](https://github.com/pydantic/pydantic), [FastAPI](https://github.com/tiangolo/fastapi), [FastAPI-Users](https://github.com/fastapi-users/fastapi-users), [Beanie](https://github.com/BeanieODM/beanie), [MongoDB](https://github.com/mongodb/mongo), [Elasticsearch](https://github.com/elastic/elasticsearch), ...
 
 #### Tekst-Web
-The client part of the Tekst platform: [`Tekst-Web/`](Tekst-Web) \
+The client part of the Tekst platform, located in [`Tekst-Web/`](Tekst-Web). \
 [TypeScript](https://github.com/microsoft/TypeScript), [Vue.js 3](https://github.com/vuejs/core), [Pinia](https://github.com/vuejs/pinia), [Naive UI](https://github.com/tusen-ai/naive-ui), [Vue I18n](https://github.com/intlify/vue-i18n), [OpenAPI-TypeScript & OpenAPI-Fetch](https://github.com/openapi-ts/openapi-typescript), ...
 
 #### Tekst Documentation
-The official docs for the Tekst platform (published [here](https://vedawebproject.github.io/Tekst)): [`docs/`](docs) \
-[MkDocs](https://github.com/mkdocs/mkdocs), [Material for MkDocs](https://github.com/squidfunk/mkdocs-material), [PyMdown Extensions](https://github.com/facelessuser/pymdown-extensions), ...
+The official [manual and technical documentation](https://vedawebproject.github.io/Tekst) for the Tekst platform, located in [`docs/`](docs). \
+[Zensical](https://github.com/zensical/zensical), [PyMdown Extensions](https://github.com/facelessuser/pymdown-extensions), ...

dev/compose.yml

@@ -92,21 +92,6 @@ services:
       - dev
       - test
 
-  docs:
-    build:
-      dockerfile_inline: |
-        FROM squidfunk/mkdocs-material:9.6.20
-        RUN pip install mkdocs-include-markdown-plugin
-    image: localhost/tekst/mkdocs-material
-    restart: unless-stopped
-    volumes:
-      - ../docs:/docs:ro
-      - ../Tekst-Web/i18n/help/enUS:/includes:ro
-    ports:
-      - 127.0.0.1:8091:8000
-    profiles:
-      - docs
-
 volumes:
   mongo_configdb:
   mongo_db:

docs/.gitignore

@@ -0,0 +1 @@
+site/

docs/README.md

@@ -1,11 +1,9 @@
 # Tekst Documentation
 
-## Development
-
-To run the development server for locally previewing changes in the documentation, use the compose file in `dev/` from the repository root:
+To run the development server for locally previewing changes in the documentation, run this command in the repository root (or replace `${PWD}/docs` by `${PWD}` if you run it from the `docs/` directory):
 
 ```
-docker compose -f dev/compose.yml --profile docs -p tekst-docs up
+docker run --rm -it -p 127.0.0.1:8080:8000 -v ${PWD}/docs:/docs zensical/zensical
 ```
 
-Then, visit `http://127.0.0.1:8091` using your web browser.
+Then, visit `http://127.0.0.1:8080` using your web browser.

docs/content/assets/logo.png

@@ -0,0 +1,5 @@
+# Contributing
+
+Tekst is explicitly meant as an Open Source project and is thus open for community contributions. You are welcome to open Pull Requests with bug fixes or feature implementations.
+
+That being said, to keep you from doing superfluous work, please [open an issue](https://github.com/VedaWebProject/Tekst/issues) first and describe a bug or feature idea to discuss the matter with a project maintainer before you start working on things ♥

docs/content/development/contributing.md

@@ -1,53 +1,61 @@
 # Introduction
 
-Tekst is a collaborative, web-based research platform for aligning, displaying, linking, exploring, and enriching resources on natural language texts. It is developed within the scope of the [VedaWeb 2.0](https://vedaweb.uni-koeln.de/) research project, where it constitutes the technical basis of the *VedaWeb* research platform.
+!!! warning "Work-in-progress"
+    While the Tekst platform software is already in its open beta phase, this manual is still very much work-in-progress. We'll try to complete it as soon as possible, but please bear with us if you encounter any incomplete information.
 
-!!! info "Git Repository"
-    You are looking for Tekst's Git repository? [It's over here.](https://github.com/VedaWebProject/Tekst)
+## What is Tekst?
 
-!!! warning "Work-in-progress"
-    While the Tekst platform is already in its open beta phase, this manual is still very much work-in-progress. We'll try to complete it as soon as possible, but please bear with us if you encounter any incomplete information.
+Tekst is a collaborative, web-based research platform for aligning, displaying, linking, exploring, and enriching resources on natural language texts. It has been initially developed within the scope of the VedaWeb 2.0 project to serve as the technical basis of the [VedaWeb](https://vedaweb.uni-koeln.de/) research platform for the linguistic study of Old Indo-Aryan texts.
+
+But its design is not limited to the study of any particular language or text type as it is meant to be project-agnostic and handle multimodal resources on arbitrary texts.
 
 ## Use cases
 
-Tekst is primarily meant as a platform software for philological research projects. The original intent for the development of Tekst was to create the technical basis for the online research platform [VedaWeb](https://vedaweb.uni-koeln.de/), where numerous resources on multiple Old Indic Sanskrit texts can be browsed, compared and searched. These include text versions, translations, annotations, audio recordings of recitations and references to external sources, which are all aligned to the structure of their respective reference texts.
+Tekst is primarily meant as a platform software for philological research projects. The original task for Tekst was to provide a central research community platform for the VedaWeb project and its research data, including text versions, translations, annotations, audio recordings of recitations and references to external sources, which are all aligned to the structure of their respective reference texts.
 
 Therefore, the main use cases for Tekst are comparable research projects that either want to publish and showcase their research data, simply curate a set of established resources on certain reference texts, or even encourage the research community to participate and contribute to a central platform dedicated to provide relevant resources.
 
 In the end, giving it a try on your local machine [is relatively easy](setup/installation.md#docker-based-deployment-recommended).
 
 ## Features
 
+!!! info
+    - [x] This is a feature is already implemented.
+    - [ ] This is a feature that is planned but not yet implemented.
+
 This list is far from exhaustive, but includes some features that might be decisive in certain scenarios:
 
-- Manage multiple independent, potentially differently structured texts
-- Run it as a closed, internally curated publishing platform or as an open platform for a selected research community to encourage user contributions
-- Built-in user management with authentication and a combination of role-based and ownership-based authorization
-- Built-in [i18n](https://en.wikipedia.org/wiki/Internationalization_and_localization) with an extensible set of languages (contributions are welcome!)
-- Encouraging user contributons and collaboration by enabling user to
-    - submit quick correction notes
-    - create versions of existing resources to compose and propose deviating data
-    - create own resources, propose them for publication and have them reviewed by the community
-- Per-resource data export (full or range-based) as JSON or CSV
-- Dozens of specialized usability features, developed with real-world needs of humanities researchers in mind
-- Extensively typed and documented server API (via [OpenAPI](https://spec.openapis.org/oas/v3.0.2) specification) and built-in interactive API documentation (via [Swagger UI](https://github.com/swagger-api/swagger-ui) and/or [ReDoc](https://github.com/Redocly/redoc)), all thanks to [FastAPI](https://github.com/tiangolo/fastapi)
-- Customize logos, UI colors, fonts, on-screen keyboards, ...
-- Built-in user messaging system
-- Publish data from various multi-modal resources, aligned to the structure of their respective common reference text
-    - Plain text
-    - Rich text
-    - Text annotations
-    - Images
-    - Audio
-    - External references
-    - Integration of external APIs
-    - Arbitrary key-value metadata
-- ...
+- [x] Manage multiple independent, potentially **differently structured texts**
+- [x] Run it as a **closed, internally curated** publishing platform **or as an open platform** for a selected research **community** to encourage user **contributions**
+- [x] Built-in **user management** with authentication and a combination of role-based and ownership-based authorization
+- [x] Built-in [i18n](https://en.wikipedia.org/wiki/Internationalization_and_localization) with an extensible set of languages (contributions are welcome!)
+- [x] Encouraging **user contributons and collaboration** by enabling user to
+    - [x] submit quick correction notes
+    - [x] create versions of existing resources to compose and propose deviating data
+    - [x] create own resources, propose them for publication and have them reviewed by the community
+- [x] Per-resource data **export** (full or range-based) as JSON or CSV
+- [x] Dozens of **specialized usability features**, developed with **real-world needs of scholars** in mind
+- [x] Content **archiving and versioning**
+- [x] Flexible **citation** hints and URLs to specific contents from specific resources at a certain point in time
+- [x] Extensively **typed and documented server API** (via [OpenAPI](https://spec.openapis.org/oas/v3.0.2) specification) and built-in interactive API documentation (via [Swagger UI](https://github.com/swagger-api/swagger-ui) and/or [ReDoc](https://github.com/Redocly/redoc)), all thanks to [FastAPI](https://github.com/tiangolo/fastapi)
+- [x] **Customize** logos, UI colors, fonts, on-screen keyboards, ...
+- [x] Built-in **user messaging** system
+- [ ] Publish data from various **multi-modal resources**, aligned to the structure of their respective common **reference text**
+    - [x] Plain text
+    - [x] Rich text
+    - [x] Text annotations
+    - [x] Images
+    - [x] Audio
+    - [ ] Video
+    - [ ] 3D models
+    - [x] External references
+    - [x] Integration of external APIs
+    - [x] Arbitrary key-value metadata
 
 ## Caveats
 
 Depending on your requirements, you might want to consider the following list of potential shortcomings:
 
 - SEO: The web client is a [SPA](https://en.wikipedia.org/wiki/Single-page_application) that is rendered in the browser (no SSR). As a result, visibility to search engines is somewhat limited.
 - No built-in functionality for uploading and managing media files. If you want to integrate image- or audio-based resources, you will have to host the respective media files yourself and link to them from your resources.
-- ... _(get in touch if you find anything that should be added to this list, we mean it!)_
+- _...get in touch if you find anything that should be added to this list, we mean it!_

docs/content/index.md

@@ -33,9 +33,9 @@ The instructions below will help you deploy a stack consisting of everything Tek
 
 1. Create a directory to store your Tekst deployment data in and enter it:
 
-   ```sh
-   mkdir my-tekst-instance && cd my-tekst-instance
-   ```
+    ```sh
+    mkdir my-tekst-instance && cd my-tekst-instance
+    ```
 
 2. Copy the compose file template from [here](https://raw.githubusercontent.com/VedaWebProject/Tekst/refs/heads/main/compose.yml) and save it as `compose.yml`: