Support custom corpus documentation templates
Mount a directory with Kalamar templates into the kalamar container, so
users can describe their own corpus in the KorAP user interface instead
of the placeholder page Kalamar shows by default. It defaults to
./custom and is created on demand; KALAMAR_TEMPLATES points it
elsewhere.
The mount itself is part of KorAP-Docker's compose file, whose
custom/README.md documents the available templates and ships examples;
this project only passes the directory through.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Change-Id: I7a1250020c2625b38dee2c1e4c33508f5af1eb8e
diff --git a/.gitignore b/.gitignore
index a2efa56..0ed2fda 100644
--- a/.gitignore
+++ b/.gitignore
@@ -33,3 +33,7 @@
# Log files
*.log
+
+# Kalamar templates describing your corpus (created on demand by `make korap`,
+# see KALAMAR_TEMPLATES). Track them in your own repository if you like.
+/custom/
diff --git a/Makefile b/Makefile
index 2488165..3fca452 100644
--- a/Makefile
+++ b/Makefile
@@ -10,6 +10,14 @@
KALAMAR_INSTANCE ?=
KALAMAR_INSTANCE_DIR := $(abspath $(KALAMAR_INSTANCE))
+# Directory with Kalamar templates describing your own corpus, mounted into the
+# kalamar container. Put a doc/corpus.html.ep page there to replace Kalamar's
+# placeholder corpus page; KorAP-Docker's custom/README.md lists the available
+# templates and ships examples. The directory is created on demand.
+# make korap KALAMAR_TEMPLATES=my-corpus-docs
+KALAMAR_TEMPLATES ?= custom
+KALAMAR_TEMPLATES_DIR := $(abspath $(KALAMAR_TEMPLATES))
+
# Optional: override the kalamar container image (e.g. a locally built tag).
# The instance's compose.instance.yaml already defaults to a renderer-capable
# image; set this to test a specific build, e.g.
@@ -205,7 +213,8 @@
java -jar lib/Krill-Indexer.jar -c lib/krill.cfg --progress -i $(subst " ",;,$^) -o $@
korap: check-src $(TARGET_DIR)/index
- curl -s https://raw.githubusercontent.com/KorAP/KorAP-Docker/master/compose.yaml | sed 's/64543:64543/$(KORAP_PORT):64543/g' | COMPOSE_PROFILES='export,open,lite' INDEX='$(TARGET_DIR)/index' $(if $(KALAMAR_INSTANCE),KALAMAR_INSTANCE_DIR='$(KALAMAR_INSTANCE_DIR)') $(if $(KALAMAR_IMAGE),KALAMAR_IMAGE='$(KALAMAR_IMAGE)') docker compose -p korap -f - $(if $(KALAMAR_INSTANCE),-f '$(KALAMAR_INSTANCE_DIR)/compose.instance.yaml') up
+ mkdir -p '$(KALAMAR_TEMPLATES_DIR)'
+ curl -s https://raw.githubusercontent.com/KorAP/KorAP-Docker/master/compose.yaml | sed 's/64543:64543/$(KORAP_PORT):64543/g' | COMPOSE_PROFILES='export,open,lite' INDEX='$(TARGET_DIR)/index' KALAMAR_TEMPLATES='$(KALAMAR_TEMPLATES_DIR)' $(if $(KALAMAR_INSTANCE),KALAMAR_INSTANCE_DIR='$(KALAMAR_INSTANCE_DIR)') $(if $(KALAMAR_IMAGE),KALAMAR_IMAGE='$(KALAMAR_IMAGE)') docker compose -p korap -f - $(if $(KALAMAR_INSTANCE),-f '$(KALAMAR_INSTANCE_DIR)/compose.instance.yaml') up
$(TARGET_DIR)/index.tar.xz: $(TARGET_DIR)/index
tar -I 'xz -T0' -C $(dir $<) -cf $@ $(notdir $<)
diff --git a/Readme.md b/Readme.md
index 180924d..65256fd 100644
--- a/Readme.md
+++ b/Readme.md
@@ -26,6 +26,30 @@
Then open the corresponding URL (e.g., http://localhost:64544) in your browser.
+### Describing your corpus in the user interface
+
+The KorAP UI has a *Corpus* entry in its documentation menu that shows a
+placeholder page until you describe the corpus you are serving. To fill it,
+put a `doc/corpus.html.ep` template into the `custom` directory:
+
+```bash
+mkdir -p custom/doc
+$EDITOR custom/doc/corpus.html.ep
+make korap
+```
+
+Such a template is mostly HTML, with `<%= ... %>` for embedded Perl; a file
+ending in `.html.md` is rendered as Markdown instead. KorAP-Docker's
+[custom/README.md](https://github.com/KorAP/KorAP-Docker/blob/master/custom/README.md)
+lists the templates you can provide -- including a references page stating how
+your corpus should be cited -- and ships commented examples.
+
+Use `KALAMAR_TEMPLATES` to keep those templates elsewhere:
+
+```bash
+make korap KALAMAR_TEMPLATES=my-corpus-docs
+```
+
### Testing a Kalamar instance's customizations
By default the KorAP UI comes up as stock Kalamar. To test the config and