Switch to zensical and add new architecture diagram

.github/actions/build/action.yml

@@ -1,17 +1,13 @@
 ---
 name: Build
-description: Setup to run and run mkdocs
+description: Setup to install dependencies and build docs with zensical
+inputs:
+  site_url:
+    description: 'Override site_url (e.g. for PR previews)'
+    required: false
+    default: "https://islandora.github.io/documentation/"
 runs:
   using: "composite"
   steps:
-    - name: Setup build environment
-      uses: actions/setup-python@v4
-      with:
-        python-version: '3.x'
-        cache: 'pip'
-    - name: Install build requirements
+    - run: make build SITE_URL="${{ inputs.site_url }}"
       shell: bash
-      run: pip install -r requirements.txt
-    - name: Build docs
-      shell: bash
-      run: mkdocs build

.github/workflows/docs-preview.yml

@@ -21,6 +21,8 @@ jobs:
         uses: actions/checkout@v3
       - name: Build docs
         uses: ./.github/actions/build
+        with:
+          site_url: https://islandora.github.io/documentation/pr-preview/pr-${{ github.event.number }}/
       - name: Deploy docs preview
         # XXX: Avoid attempting to do preview things across fork boundaries, as it doesn't work.
         # See: https://github.com/rossjrw/pr-preview-action/pull/6

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.12-alpine3.22
+
+WORKDIR /work
+
+RUN apk add --no-cache git && \
+    pip install uv && uv --version && \
+    uv pip install --break-system-packages --system zensical==0.0.29
+
+EXPOSE 8080
+
+ENTRYPOINT ["zensical"]
+CMD ["serve", "--dev-addr", "0.0.0.0:8080"]

Makefile

@@ -0,0 +1,39 @@
+.PHONY: docker-build build abbreviations help preview serve
+
+help: ## Show this help message
+	echo 'Usage: make [target]'
+	echo ''
+	echo 'Available targets:'
+	awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  \033[36m%s\033[0m\t%s\n", $$1, $$2}' $(MAKEFILE_LIST) | sort | column -t -s $$'\t'
+
+abbreviations: ## Parse ./docs/user-documentation/glossary.md and create Zensical Snippets other docs can reference
+	./scripts/generate-abbreviations.sh
+
+docker-build: ## Build the Zensical python application
+	docker build -t islandora-docs .
+
+build: docker-build ## Run zensical build --clean
+	rm -rf site
+	docker run --rm \
+		$(if $(SITE_URL),-e SITE_URL=$(SITE_URL)) \
+		-v "$(CURDIR):/work" \
+		-w /work \
+		islandora-docs \
+		build --clean
+
+serve: docker-build ## Run zensical serve to make the docs available at http://localhost:8080. You can then make live updates to the docs.
+	docker run --rm -it \
+		-p 8080:8080 \
+		-v "$(CURDIR):/work" \
+		-w /work \
+		islandora-docs
+
+preview: ## Make the contents from zensical build --clean available at http://localhost:8080. Use for troubleshooting GitHuub Pages issues.
+	$(MAKE) build SITE_URL=http://localhost:8080
+	docker run --rm -it \
+		-p 8080:8080 \
+		-v "$(CURDIR)/site:/site" \
+		-w /site \
+		--entrypoint python3 \
+		islandora-docs \
+		-m http.server 8080

docs/contributing/docs-style-guide.md

@@ -8,7 +8,7 @@
 - Submit documentation formatted in [Markdown](https://en.wikipedia.org/wiki/Markdown) format.
     - Include a top-level heading for the whole page (using `#`)
     - Please add Markdown headings (`#` and `##`) to the content sections.
-
+- Wrap glossary terms used in Markdown with brackets `[]` when you want that term to leverage [Zensical's snippets/glossary](https://zensical.org/docs/authoring/tooltips/#add-a-glossary) feature. A snippet provides the definition of a term without needing to look it up in the glossary by simply mousing over the term.
 - Use the "bold/emphasis" style in Markdown by enclosing text in double asterisks or underscores, `**bold text**` or `__bold text__`, for UI elements that users will interact with. For example, a button label for a button that must be pressed should be made bold in Markdown.
 - Use the "italics" style in Markdown by enclosing text in single asterisks or underscores, `*italic text*` or `_italic text_`, for UI elements that have a label or title if you need to reference them in the documentation. For example, a title of a screen or page that will visit should be made italic in Markdown.
 - Use `>>` and `**bold text**` to indicate clicking through nested menu items, and also include the direct path. _Example:_

docs/css/custom.css

@@ -1,4 +1,3 @@
-
 .md-typeset .admonition.islandora,
 .md-typeset details.islandora {
   border-color: rgb(194, 19, 19);
@@ -22,3 +21,118 @@
   --text: #f5fffa;
 }
 
+/** Mermaid animation helpers for stepped flow diagrams. */
+@keyframes dash {
+  to {
+    stroke-dashoffset: -100;
+  }
+}
+
+/**
+ * Sequential flow animation for Mermaid diagrams.
+ *
+ * Author diagrams by assigning flow step classes to edges:
+ *
+ *   class e1 flow0;
+ *   class e2 flow1;
+ *   class e3 flow2;
+ *
+ * The JavaScript runtime finds flow0..flow10-style classes, applies the dash
+ * styling, and animates those steps in sequence. Edges sharing the same flowN
+ * value animate in parallel. By default each step lasts 3 s, followed by a 2 s
+ * pause before the full sequence repeats.
+ */
+@keyframes dashFlash {
+  0%    { stroke-dashoffset: 900; }
+  12.5% { stroke-dashoffset: -100; }
+  12.6% { stroke-dashoffset: 900; }
+  100%  { stroke-dashoffset: 900; }
+}
+
+.mermaid-expandable {
+  cursor: zoom-in;
+}
+
+.mermaid-expandable:focus-visible {
+  outline: 2px solid var(--md-accent-fg-color);
+  outline-offset: 0.3rem;
+}
+
+.mermaid-lightbox {
+  background: transparent;
+  border: 0;
+  max-width: min(96vw, 1400px);
+  padding: 0;
+  width: 96vw;
+}
+
+.mermaid-lightbox::backdrop {
+  background: rgba(0, 0, 0, 0.72);
+}
+
+.mermaid-lightbox__frame {
+  background: var(--md-default-bg-color);
+  border-radius: 0.6rem;
+  box-shadow: var(--md-shadow-z3);
+  max-height: 90vh;
+  overflow: hidden;
+}
+
+.mermaid-lightbox__close {
+  appearance: none;
+  background: transparent;
+  border: 1px solid currentColor;
+  border-radius: 999px;
+  cursor: pointer;
+  display: block;
+  margin: 1rem 1rem 0 auto;
+  padding: 0.35rem 0.75rem;
+}
+
+.mermaid-lightbox__body {
+  overflow: auto;
+  padding: 1rem;
+}
+
+.mermaid-lightbox__body svg {
+  display: block;
+  margin: 0 auto;
+}
+
+/** Play / Pause / Restart controls injected below animated diagrams **/
+.mermaid-controls {
+  display: flex;
+  gap: 0.3rem;
+  justify-content: center;
+  margin-top: 0.5rem;
+}
+
+.mermaid-controls .mermaid-btn {
+  appearance: none;
+  background: transparent;
+  border: 1px solid currentColor;
+  border-radius: 3px;
+  cursor: pointer;
+  font-size: 0.8rem;
+  line-height: 1;
+  opacity: 0.35;
+  padding: 0.25rem 0.5rem;
+  transition: opacity 0.15s;
+}
+
+.mermaid-controls .mermaid-btn:hover,
+.mermaid-controls .mermaid-btn:focus-visible {
+  opacity: 0.85;
+}
+
+.mermaid-controls .mermaid-btn:disabled {
+  cursor: default;
+  opacity: 0.85;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .mermaid * {
+    animation: none !important;
+    transition: none !important;
+  }
+}

docs/installation/component-overview.md

@@ -9,59 +9,60 @@ This list includes four different kinds of components:
 - Components that can't easily be swapped out but are not necessarily required (such as using Solr as the site's internal search engine)
 - Components which do not have official alternatives and are not necessarily required, but will likely exist on the vast majority of Islandora installations (such as Alpaca and Crayfish)
 
-## The Webserver Stack - Apache, PHP, and MySQL/PostgreSQL
+## The Webserver Stack - Traefik, NGINX, PHP, and MariaDB (or PostgreSQL)
 
-Combined together, Apache, PHP, and MySQL/PostgreSQL comprise a LAMP or LAPP server used to provide end-user-facing components - namely, the website.
+Combined together, [Traefik], [NGINX], PHP, and [MariaDB] (or [PostgreSQL]) comprise a solution stack used to provide end-user-facing components - namely, the website.```
 
-**Apache** is the webserver that will serve up webpages to the public. It will also manage some internal functionality provided by Crayfish, and will expose Cantaloupe to the public. We’ll be making changes to the VirtualHost entry, enabling some modules, and modifying the ports configuration. The VirtualHost entry will eventually be modified when we need to expose other services like Cantaloupe to the public.
+**[Traefik]** acts as the Islandora stack's front-end proxy. It will terminate TLS and routes requests to services in the Islandora stack i.e. Drupal, Cantaloupe, and Fedora.
 
-**PHP** is the runtime interpreter for all the code Drupal and Crayfish need to be processed. By default, installing PHP 7.2 will give us a command-line interpreter, as well as an interpreter for Apache. We’re going to install several PHP modules required and/or useful for the components that make use of PHP.
 
-**MySQL** and **PostgreSQL** are database management systems that we will use to store information for many different components like Drupal and Fedora. By default, the Ansible playbook installs MySQL, though this can be switched to PostgreSQL. The manual installation guide recommends and walks through installing and using PostgreSQL.
+**[NGINX]** is the webserver that will serve up webpages to the public.
 
-## The Front-Facing CDM - Composer, Drush, and Drupal
+**PHP** is the runtime interpreter for all the code Drupal needs to be processed. By default, installing PHP 8.3 will give us a command-line interpreter, as well as an interpreter for NGINX. 
 
-Composer will be used to install both Drupal and Drush simultaneously using Islandora's fork of the [drupal-project](https://github.com/Islandora/drupal-project) repository.
+**[MariaDB]** and **[PostgreSQL]** are database management systems that we will use to store information for many different components like Drupal and Fedora. By default, the [ISLE Site Template] installs MariaDB, though this can be switched to PostgreSQL.
 
-**Composer** is an installer and dependency manager for PHP projects. We're going to need it to install components for any PHP code we need to make use of, including Drupal and Crayfish.
+## Composer, Drush, and Drupal
 
-**Drush** and **Drupal** are installed simultaneously using [drupal-project](https://github.com/Islandora/drupal-project). Drupal will serve up webpages and manage Islandora content, and Drush will help us get some things done from the command-line.
+Composer will be used to install both Drupal and Drush simultaneously using [Islandora Starter Site]
+
+**[Composer]** is an installer and dependency manager for PHP projects. We're going to need it to install components for Drupal.
+
+**[Drush]** and **[Drupal]** are installed simultaneously using [Composer]. Drupal will serve up webpages and manage Islandora content, and Drush will help us get some things done from the command-line.
 
 ## The Web Application Server - Tomcat and Cantaloupe
 
-Several applets will be deployed via their `.war` files into Tomcat, including Fedora and Cantaloupe.
+Several applets will be deployed via their `.war` files into Tomcat, including [Fedora (Repository Software)] and [Cantaloupe].
 
-**Tomcat** serves up webpages and other kinds of content much like Apache, but is specifically designed to deploy Java applications as opposed to running PHP code.
+**[Tomcat]** serves up webpages and other kinds of content much like NGINX, but is specifically designed to deploy Java applications as opposed to running PHP code.
 
-**Cantaloupe** is an image tileserver that Islandora will connect to and use to serve up extremely large images in a way that doesn't have an adverse effect on the overall system.
+**[Cantaloupe]** is an image tileserver that Islandora will connect to and use to serve up extremely large images in a way that doesn't have an adverse effect on the overall system.
 
-## The Back-End File Management Repository - Fedora, Syn, and Blazegraph
+## The Back-End File Management Repository - Fedora and Blazegraph
 
 Fedora will be installed in its own section, rather than as part of the Tomcat installation, as the installation process is rather involved and requires some authorization pieces to be set up in order to connect them back to Drupal and other components.
 
-**Fedora** is the default backend repository that Islandora content will be synchronized with and stored in. A great deal of configuration will be required to get it up and running, including ensuring a database is created and accessible.
-
-**Syn** is the authorization piece that allows Fedora to connect to other components.
+**[Fedora (Repository Software)]** is the default backend repository that Islandora content will be synchronized with and stored in. A great deal of configuration will be required to get it up and running, including ensuring a database is created and accessible.
 
-**Blazegraph** will store representative graph data about the repository that can be queried using SPARQL. Some configuration will also be required to link it back to Fedora, as well as to ensure it is being properly indexed.
+**[Blazegraph]** will store representative graph data about the repository that can be queried using SPARQL. Some configuration will also be required to link it back to Fedora, as well as to ensure it is being properly indexed.
 
 ## The Search Engine - Solr and search_api_solr
 
 The installation of Solr itself is rather straightforward, but a configuration will have to be generated and applied from the Drupal side.
 
-**Solr** will be installed as a standalone application. Nothing of particular importance needs to happen here; the configuration will be applied when `search_api_solr` is installed.
+**[Solr]** will be installed as a standalone application. Nothing of particular importance needs to happen here; the configuration will be applied when `search_api_solr` is installed.
 
 **search_api_solr** is the Drupal module that implements the Solr API for Drupal-side searches. After installing and configuring the module, the `drush solr-gsc` command will be used to generate Solr configs, and these configs will be moved to the Solr configuration location.
 
-## The Asynchronous Background Services - Crayfish
+## The Asynchronous Background Services - scyllaridae
 
-**Crayfish** is a series of microservices that perform different asynchronous tasks kicked off by Islandora. It contains a series of submodules that will be installed via Composer. Later, these configured components will be connected to Alpaca.
+**[scyllaridae]** is a series of microservices that perform different asynchronous tasks kicked off by Islandora. It contains a series of submodules that will be installed via Composer. Later, these configured components will be connected to Alpaca.
 
 ## The Broker Connecting Everything - Karaf and Alpaca
 
 **Karaf**’s job is similar to Tomcat, except where Tomcat is a web-accessible endpoint for Java applets, Karaf is simply meant to be a container for system-level applets to communicate via its OSGI. Alpaca is one such applet; it will broker messages between Fedora and Drupal, and between Drupal and various derivative generation applications.
 
-**Alpaca** contains Karaf services to manage moving information between Islandora, Fedora, and Blazegraph as well as kicking off derivative services in Crayfish. These will be configured to broker between Drupal and Fedora using an ActiveMQ queue.
+**[Alpaca]** contains Karaf services to manage moving information between Islandora, Fedora, and Blazegraph as well as kicking off derivative services in Crayfish. These will be configured to broker between Drupal and Fedora using an ActiveMQ queue.
 
 ## Finalized Drupal Configurations