markpublish 2.3.0__tar.gz → 2.3.2__tar.gz

{markpublish-2.3.0/src/markpublish.egg-info → markpublish-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markpublish
-Version: 2.3.0
+Version: 2.3.2
 Summary: Modern, modular, and extensible Markdown-to-PDF publishing tool powered by Typst
 Author-email: Frank Winter <studio@frankwinter.com>
 License: MIT

{markpublish-2.3.0 → markpublish-2.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "markpublish"
-version = "2.3.0"
+version = "2.3.2"
 description = "Modern, modular, and extensible Markdown-to-PDF publishing tool powered by Typst"
 readme = "README.md"
 license = { text = "MIT" }

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/__init__.py

@@ -2,5 +2,5 @@
 markpublish - Modern, modular Markdown-to-PDF publishing tool powered by Typst.
 """
 
-__version__ = "2.3.0"
+__version__ = "2.3.2"
 

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/config/loader.py

@@ -6,8 +6,11 @@ from __future__ import annotations
 
 import copy
 import datetime
+import urllib.error
+import urllib.request
 from pathlib import Path
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, FrozenSet, Optional, Union
+from urllib.parse import urljoin, urlparse
 
 import yaml
 
@@ -25,6 +28,70 @@ def format_current_date(language: Optional[str] = None) -> str:
     return now.strftime("%Y-%m-%d")
 
 
+#: Woher eine Konfiguration stammt: Verzeichnis einer Datei oder eine URL.
+#: Relative Verweise mit `!file` loesen sich dagegen auf.
+Base = Union[Path, str]
+
+FILE_TAG = "!file"
+YAML_SUFFIXES = (".yaml", ".yml")
+URL_TIMEOUT = 10
+
+
+def _is_url(src: str) -> bool:
+    return src.startswith(("http://", "https://"))
+
+
+def _resolve_ref(src: str, base: Base) -> Union[Path, str]:
+    """Absoluter Ort eines `!file`-Verweises, relativ zu der Datei, in der er steht."""
+    if _is_url(src):
+        return src
+    if isinstance(base, str):
+        return urljoin(base, src)
+    return (base / src).resolve()
+
+
+def _read_ref(target: Union[Path, str], src: str) -> str:
+    if isinstance(target, str):
+        try:
+            with urllib.request.urlopen(target, timeout=URL_TIMEOUT) as response:
+                return response.read().decode("utf-8")
+        except (urllib.error.URLError, OSError, UnicodeDecodeError) as exc:
+            raise ValueError(t("err.config.file_ref_url", src=src, reason=exc)) from exc
+    if not target.is_file():
+        raise FileNotFoundError(t("err.config.file_ref_missing", src=src, path=target))
+    return target.read_text(encoding="utf-8")
+
+
+def _load_yaml(text: Any, base: Base, seen: FrozenSet[Union[Path, str]] = frozenset()) -> Any:
+    """
+    Wie `yaml.safe_load`, zusaetzlich mit `!file "pfad-oder-url"`.
+
+    Ein Verweis auf .yaml/.yml setzt deren Inhalt an seine Stelle, jede
+    andere Datei ihren Text. Nachgeladene YAML-Dateien duerfen selbst wieder
+    `!file` enthalten; deren Pfade gelten relativ zu ihnen. `seen` haelt die
+    Kette der offenen Dateien -- dieselbe Datei in zwei Zweigen ist erlaubt,
+    nur ein Verweis zurueck in die eigene Kette nicht.
+    """
+
+    def construct(loader: yaml.SafeLoader, node: yaml.Node) -> Any:
+        src = loader.construct_scalar(node)
+        target = _resolve_ref(src, base)
+        if target in seen:
+            raise ValueError(t("err.config.file_ref_cycle", src=src, path=target))
+        content = _read_ref(target, src)
+        name = urlparse(target).path if isinstance(target, str) else target.name
+        if not name.lower().endswith(YAML_SUFFIXES):
+            return content.rstrip("\n")
+        child_base = target if isinstance(target, str) else target.parent
+        return _load_yaml(content, child_base, seen | {target})
+
+    # Eigene Loader-Klasse je Aufruf: der Konstruktor haengt an `base` und
+    # `seen`, und SafeLoader selbst soll unveraendert bleiben.
+    loader_cls = type("_FileLoader", (yaml.SafeLoader,), {})
+    loader_cls.add_constructor(FILE_TAG, construct)
+    return yaml.load(text, Loader=loader_cls)  # noqa: S506 - SafeLoader-Unterklasse
+
+
 def load_config(config_path_or_str: Union[str, Path, Dict[str, Any]]) -> MarkpublishConfig:
     """
     Loads and validates a markpublish configuration.
@@ -44,8 +111,9 @@ def load_config(config_path_or_str: Union[str, Path, Dict[str, Any]]) -> Markpub
     elif isinstance(config_path_or_str, Path):
         if not config_path_or_str.is_file():
             raise FileNotFoundError(t("err.config.not_found_file", path=config_path_or_str))
-        with open(config_path_or_str, "r", encoding="utf-8") as f:
-            loaded = yaml.safe_load(f)
+        config_path = config_path_or_str.resolve()
+        with open(config_path, "r", encoding="utf-8") as f:
+            loaded = _load_yaml(f, config_path.parent, frozenset({config_path}))
             if loaded is None:
                 raise ValueError(t("err.config.expected_mapping", type="empty"))
             if not isinstance(loaded, dict):
@@ -56,8 +124,9 @@ def load_config(config_path_or_str: Union[str, Path, Dict[str, Any]]) -> Markpub
         # YAML-Text mit Zeilenumbruch ist nie ein Pfad; ein langer liesse is_file()
         # unter Linux/macOS vor Python 3.14 mit ENAMETOOLONG scheitern.
         if "\n" not in config_path_or_str and candidate_path.is_file():
-            with open(candidate_path, "r", encoding="utf-8") as f:
-                loaded = yaml.safe_load(f)
+            config_path = candidate_path.resolve()
+            with open(config_path, "r", encoding="utf-8") as f:
+                loaded = _load_yaml(f, config_path.parent, frozenset({config_path}))
                 if loaded is None:
                     raise ValueError(t("err.config.expected_mapping", type="empty"))
                 if not isinstance(loaded, dict):
@@ -78,7 +147,7 @@ def load_config(config_path_or_str: Union[str, Path, Dict[str, Any]]) -> Markpub
 
             # Versuche als YAML-String zu parsen
             try:
-                loaded = yaml.safe_load(config_path_or_str)
+                loaded = _load_yaml(config_path_or_str, Path.cwd())
             except yaml.YAMLError as exc:
                 raise ValueError(str(exc)) from exc
 

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/docs/cheatsheet/de/01_config.md

@@ -34,6 +34,7 @@ Metadaten und globale Layout-Schalter. Pflichtangabe ist allein `title`.
 | `status` | – | Dokumentstatus (z. B. `Entwurf`, `Freigegeben`) |
 | `copyright` | – | Copyright-Hinweis auf dem Deckblatt |
 | `language` | Systemsprache | ISO-Sprachcode für statische Beschriftungen (`de`, `en`) |
+| `custom` | – | Eigene Werte für Platzhalter im Text (`{{custom.a.b}}`), auch verschachtelt |
 | `cover` | `false` | Deckblatt erzeugen |
 | `header` / `footer` | `true` | Kopf- und Fußzeilen aktivieren |
 | `document_toc` | `full` | Haupt-Inhaltsverzeichnis: `none`, `full` oder Tiefe als Zahl |
@@ -49,6 +50,10 @@ Besteht das Dokument aus **genau einem Kapitel**, lässt das Haupt-Inhaltsverzei
 
 Eigene Zusatzfelder unter `document:` (`abteilung: "F&E"`) erreichen das Theme über das Wörterbuch `meta` (`meta.at("abteilung").value`). Statische Beschriftungen gehören in die `i18n.yaml`, nicht hierher.
 
+Im Markdown setzt `{{name}}` eine Angabe aus `document:` ein (`{{author}}`, `{{custom.verfahren.name}}`). Werte unter `custom` erreichen das Theme nicht. Ein Platzhalter ohne Wert bricht den Bau ab; `\{{author}}` bleibt wörtlich stehen.
+
+`schlüssel: !file "pfad-oder-url"` lädt einen Wert aus einer anderen Datei, überall in der Konfiguration. YAML-Dateien liefern einen verschachtelten Wert, jede andere Datei ihren Text. Relative Pfade gelten ab der verweisenden Datei.
+
 ## parts
 
 Ein Part klammert Kapitel und gibt Einstellungen an sie weiter. Ohne `break_before` zeigt er sich selbst nicht.

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/docs/cheatsheet/de/markpublish.yaml

@@ -11,7 +11,7 @@ document:
   summary: "Nachschlagewerk zu allen Schlüsseln der markpublish.yaml und den Bausteinen eines Themes."
   author: "Frank Winter"
   copyright: "© 2026 Frank Winter"
-  version: "2.3.0"
+  version: "2.3.2"
   date: "auto"
   language: "de"
 

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/docs/cheatsheet/en/01_config.md

@@ -34,6 +34,7 @@ Metadata and global layout toggles. Only `title` is required.
 | `status` | – | Document status (e.g. `Draft`, `Approved`) |
 | `copyright` | – | Copyright notice on the cover page |
 | `language` | system language | ISO code for static labels (`de`, `en`) |
+| `custom` | – | Own values for placeholders in the text (`{{custom.a.b}}`), may be nested |
 | `cover` | `false` | Generate a cover page |
 | `header` / `footer` | `true` | Running headers and footers |
 | `document_toc` | `full` | Main table of contents: `none`, `full` or a depth |
@@ -49,6 +50,10 @@ If the document consists of **exactly one chapter**, the main table of contents
 
 Custom fields under `document:` (`department: "R&D"`) reach the theme through the `meta` dictionary (`meta.at("department").value`). Static labels belong in `i18n.yaml`, not here.
 
+In Markdown, `{{name}}` inserts a value from `document:` (`{{author}}`, `{{custom.procedure.name}}`). Values under `custom` do not reach the theme. A placeholder without a value stops the build; `\{{author}}` stays as written.
+
+`key: !file "path-or-url"` loads a value from another file, anywhere in the configuration. YAML files supply a nested value, any other file its text. Relative paths resolve against the referencing file.
+
 ## parts
 
 A part brackets chapters and passes settings down to them. Without `break_before` it does not show itself.

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/docs/cheatsheet/en/markpublish.yaml

@@ -11,7 +11,7 @@ document:
   summary: "Reference for every key of markpublish.yaml and the building blocks of a theme."
   author: "Frank Winter"
   copyright: "© 2026 Frank Winter"
-  version: "2.3.0"
+  version: "2.3.2"
   date: "auto"
   language: "en"
 

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/docs/manual/de/chapters/04_configuration_guide.md

@@ -41,7 +41,35 @@ Globale Verzeichnisvorgaben
 Nummerierungsregeln
 : Vorgaben zur automatischen Nummerierung (`autonum_pattern`, `autonum_reset`).
 
-#### Eigene Metadatenfelder
+### Parts (Abschnitte)
+
+Ein Dokument wird durch `parts:` in übergeordnete Abschnitte gegliedert (z. B. „Hauptteil“, „Fallstudien“, „Anhänge“):
+
+* Ein Dokument muss immer über `parts:` aufgebaut sein; ein flaches `chapters:` direkt auf oberster Ebene wird abgewiesen.
+
+* Ein Abschnitt fasst logisch zusammengehörige Kapitel zusammen.
+
+* Ohne Angabe tritt ein Abschnitt selbst nicht in Erscheinung (`break_before: "none"`): er klammert seine Kapitel und vererbt seine Einstellungen, belegt aber keine Seite und erscheint nicht im Inhaltsverzeichnis. Mit `break_before: "divider"` erhält er eine gestaltete Trennseite, mit `break_before: "page"` eine Überschrift auf einer neuen Seite.
+
+* Auf Abschnittsebene gesetzte Einstellungen (z. B. Verzeichnistiefe oder ein `autonum_pattern`) vererben sich automatisch auf alle darin enthaltenen Kapitel.
+
+* Auf `parts:` sind ausschließlich die deklarierten Konfigurationsschlüssel erlaubt. Unbekannte Schlüssel (wie `break_befor`) werden mit Ähnlichkeitsvorschlägen abgelehnt, um unbemerkte Fehlkonfigurationen auszuschließen.
+
+### Chapters (Kapitel)
+
+Die Liste `chapters:` innerhalb eines Abschnitts verweist auf die eigentlichen Markdown-Inhaltsdateien:
+
+* Jedes Kapitel verweist auf seine Markdown-Datei (`file:`). Autoren können in ihren Markdown-Dateien ganz natürlich mit einer `#`-Überschrift beginnen.
+
+* Über **`show_title:`** (`true` oder `false`, Standard: `true`) lässt sich steuern, ob die `#`-Überschrift der Markdown-Datei auf der Inhaltsseite gerendert werden soll. Wird vor dem Kapitel eine Trennseite erzeugt (`break_before: "divider"`), kann mit `show_title: false` verhindert werden, dass der Titel auf der Folgeseite doppelt erscheint – die Inhaltsseite beginnt dann direkt mit dem Fließtext oder der ersten Zwischenüberschrift.
+
+* Über die optionalen Schlüssel **`toc_title:`** (für Inhaltsverzeichnisse und Kopfzeilen) und **`divider_title:`** (für Trennseiten) können gezielt abweichende Titel vergeben werden (z. B. eine prägnante Kurzform im Inhaltsverzeichnis gegenüber einer ausführlichen Überschrift auf der Textseite). Fehlen die Schlüssel, erben beide automatisch die `#`-Überschrift der Datei.
+
+* Soll eine Trennseite erzeugt werden (`break_before: "divider"`) oder das Kapitel im Inhaltsverzeichnis gelistet werden, muss mindestens eine `#`-Überschrift oder der entsprechende Titelschlüssel (`divider_title` / `toc_title`) vorhanden sein, andernfalls bricht der Build mit einer klaren Fehlermeldung ab.
+
+* Kapitel können über das Feld `break_before` steuern, ob vor ihnen eine Trennseite erzeugt wird, ein einfacher Seitenwechsel erfolgt oder der Text nahtlos anschließt.
+
+## Eigene Metadatenfelder
 
 Unter `document:` sind über die bekannten Schlüssel hinaus **beliebige eigene Felder** erlaubt. Sie erreichen das Theme, werden aber nicht von selbst gedruckt:
 
@@ -76,7 +104,7 @@ Drei Dinge sind dabei zu wissen:
 
 * **Der Typ bleibt erhalten.** Ein `true` ist ein Wahrheitswert und kein Text: Das Deckblatt setzt `Ja` beziehungsweise `Yes`, je nach Dokumentsprache. Die beiden Wörter stehen als `bool_true` und `bool_false` in der i18n-Kaskade.
 
-#### Platzhalter im Text
+## Platzhalter im Text
 
 Im Markdown setzt `{{name}}` eine Angabe aus `document:` ein, etwa `{{author}}`, `{{version}}` oder `{{date}}` (bei `"auto"` das errechnete Datum). Das gilt auch für eigene Metadatenfelder. Werte, die nur im Text gebraucht werden, gehören unter `custom:`. Dort dürfen sie verschachtelt sein und werden mit Punkten angesprochen:
 
@@ -94,36 +122,58 @@ Ansprechpartner: {{author}}, {{custom.support_mail}}.
 Dieses Dokument beschreibt {{custom.verfahren.name}}.
 ```
 
-Werte unter `custom` erreichen das Theme nicht. Ein Platzhalter ohne Wert, auch ein vertippter, bricht den Bau mit Angabe der Datei ab. In Code (`` `{{author}}` `` oder Codeblock) bleibt der Platzhalter wörtlich stehen, im Fließtext mit vorangestelltem Backslash: `\{{author}}` ergibt `{{author}}`.
-
-### Parts (Abschnitte)
-
-Ein Dokument wird durch `parts:` in übergeordnete Abschnitte gegliedert (z. B. „Hauptteil“, „Fallstudien“, „Anhänge“):
-
-* Ein Dokument muss immer über `parts:` aufgebaut sein; ein flaches `chapters:` direkt auf oberster Ebene wird abgewiesen.
+Ist ein eingesetzter Wert eine E-Mail-Adresse oder eine URL, wird er wie direkt geschriebener Text ein Link; steht der Platzhalter schon in einem Link, bleibt es bei diesem. Werte unter `custom` erreichen das Theme nicht. Ein Platzhalter ohne Wert, auch ein vertippter, bricht den Bau mit Angabe der Datei ab. In Code (`` `{{author}}` `` oder Codeblock) bleibt der Platzhalter wörtlich stehen, im Fließtext mit vorangestelltem Backslash: `\{{author}}` ergibt `{{author}}`.
 
-* Ein Abschnitt fasst logisch zusammengehörige Kapitel zusammen.
+### Schleifen und Kurznamen
 
-* Ohne Angabe tritt ein Abschnitt selbst nicht in Erscheinung (`break_before: "none"`): er klammert seine Kapitel und vererbt seine Einstellungen, belegt aber keine Seite und erscheint nicht im Inhaltsverzeichnis. Mit `break_before: "divider"` erhält er eine gestaltete Trennseite, mit `break_before: "page"` eine Überschrift auf einer neuen Seite.
+`{% for %}` wiederholt die Zeilen bis `{% endfor %}` für jeden Eintrag einer Gruppe unter `custom`, in der Reihenfolge der YAML-Datei. So entsteht etwa eine Tabelle mit einer Zeile je Rolle:
 
-* Auf Abschnittsebene gesetzte Einstellungen (z. B. Verzeichnistiefe oder ein `autonum_pattern`) vererben sich automatisch auf alle darin enthaltenen Kapitel.
-
-* Auf `parts:` sind ausschließlich die deklarierten Konfigurationsschlüssel erlaubt. Unbekannte Schlüssel (wie `break_befor`) werden mit Ähnlichkeitsvorschlägen abgelehnt, um unbemerkte Fehlkonfigurationen auszuschließen.
+```yaml
+document:
+  custom:
+    app:
+      roles:
+        application_owner: {label: "Verfahrensverantwortliche/r", name: "A. Muster"}
+        technical_administrator: {label: "Technische Administration", name: "B. Beispiel"}
+```
 
-### Chapters (Kapitel)
+```markdown
+| Rolle | Name | Schlüssel |
+| :--- | :--- | :--- |
+{% for (role, key) in custom.app.roles %}
+| {{role.label}} | {{role.name}} | {{key}} |
+{% endfor %}
+```
 
-Die Liste `chapters:` innerhalb eines Abschnitts verweist auf die eigentlichen Markdown-Inhaltsdateien:
+`{% set %}` gibt einem langen Pfad einen Kurznamen, der bis zum Ende der Datei gilt (innerhalb einer Schleife bis zu deren Ende):
 
-* Jedes Kapitel verweist auf seine Markdown-Datei (`file:`). Autoren können in ihren Markdown-Dateien ganz natürlich mit einer `#`-Überschrift beginnen.
+```markdown
+{% set owner = custom.app.roles.application_owner %}
+Verantwortlich ist {{owner.name}}.
+```
 
-* Über **`show_title:`** (`true` oder `false`, Standard: `true`) lässt sich steuern, ob die `#`-Überschrift der Markdown-Datei auf der Inhaltsseite gerendert werden soll. Wird vor dem Kapitel eine Trennseite erzeugt (`break_before: "divider"`), kann mit `show_title: false` verhindert werden, dass der Titel auf der Folgeseite doppelt erscheint – die Inhaltsseite beginnt dann direkt mit dem Fließtext oder der ersten Zwischenüberschrift.
+* **Anweisungen stehen allein in ihrer Zeile**; die Zeile verschwindet beim Bau vollständig, eine Tabelle bleibt also zusammenhängend. In einem Zitat oder einer Hinweisbox darf `>` davorstehen.
+* **`(role, key)`** liefert zusätzlich den Namen des Eintrags (`application_owner`); `for role in …` genügt, wenn er nicht gebraucht wird.
+* **Schleifen lassen sich schachteln.** Der Name einer Schleife gilt nur in ihr; ein Name darf keine Angabe unter `document` verdecken (`author`, `custom` …).
+* In Code und Codeblöcken bleiben Anweisungen wörtlich stehen, im Fließtext mit vorangestelltem Backslash: `\{% … %}`. Fehler wie ein fehlendes `{% endfor %}` brechen den Bau mit Datei und Zeile ab.
 
-* Über die optionalen Schlüssel **`toc_title:`** (für Inhaltsverzeichnisse und Kopfzeilen) und **`divider_title:`** (für Trennseiten) können gezielt abweichende Titel vergeben werden (z. B. eine prägnante Kurzform im Inhaltsverzeichnis gegenüber einer ausführlichen Überschrift auf der Textseite). Fehlen die Schlüssel, erben beide automatisch die `#`-Überschrift der Datei.
+## Werte aus anderen Dateien (`!file`)
 
-* Soll eine Trennseite erzeugt werden (`break_before: "divider"`) oder das Kapitel im Inhaltsverzeichnis gelistet werden, muss mindestens eine `#`-Überschrift oder der entsprechende Titelschlüssel (`divider_title` / `toc_title`) vorhanden sein, andernfalls bricht der Build mit einer klaren Fehlermeldung ab.
+Statt einen Wert direkt hinzuschreiben, lädt `!file` ihn aus einer Datei oder von einer URL nach. Beides lässt sich beliebig mischen:
 
-* Kapitel können über das Feld `break_before` steuern, ob vor ihnen eine Trennseite erzeugt wird, ein einfacher Seitenwechsel erfolgt oder der Text nahtlos anschließt.
+```yaml
+document:
+  custom:
+    a: "xxx"
+    verfahren: !file "../gemeinsam/verfahren.yaml"
+    zweck: !file "zweck.txt"
+    betreiber: !file "https://intranet.example/betreiber.yaml"
+```
 
+* **YAML-Dateien** (`.yaml`, `.yml`) setzen ihren Inhalt an die Stelle des Verweises, `{{custom.verfahren.name}}` greift also in die nachgeladene Datei. **Jede andere Datei** liefert ihren Text als einfachen Wert.
+* **Relative Pfade** gelten relativ zu der Datei, in der das `!file` steht, bei einer URL relativ zu dieser URL.
+* **Verschachtelt:** Eine nachgeladene YAML-Datei darf selbst wieder `!file` enthalten. Dieselbe Datei an mehreren Stellen ist erlaubt; ein Verweis, der über die Kette zu sich selbst zurückführt, bricht den Bau ab.
+* `!file` wirkt überall in der Konfiguration, nicht nur unter `custom`. Ein Abruf per URL wartet höchstens 10 Sekunden.
 
 ---
 

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/docs/manual/de/chapters/07_appendix_yaml_spec.md

@@ -19,7 +19,7 @@ Die Sektion `document:` legt globale Metadaten, Layoutschalter, Verzeichnisvorga
 | `date` | String | `"auto"` | Datum des Dokuments. Bei `"auto"` oder `"today"` wird das aktuelle Tagesdatum eingesetzt. |
 | `version` | String | `None` | Versionskennung (z. B. `"2.0.0"`). Wird nur gedruckt, wenn explizit gesetzt. |
 | `language` | String | *(Systemsprache)* | ISO-Sprachcode (z. B. `"de"` oder `"en"`). Steuert Silbentrennung und UI-Texte. |
-| `custom` | Mapping | `{}` | Eigene Werte für Platzhalter im Text (`{{custom.a.b}}`), auch verschachtelt. Siehe *Platzhalter im Text*. |
+| `custom` | Mapping | `{}` | Eigene Werte für Platzhalter im Text (`{{custom.a.b}}`), auch verschachtelt. Siehe *Platzhalter im Text*. Einzelne Werte oder Gruppen lassen sich mit `!file` nachladen. |
 | `cover` | Boolean | `false` | Steuert, ob eine gestaltete Deckblattseite erzeugt wird. Ohne Angabe beginnt das Dokument mit dem ersten Inhalt. |
 | `header` | Boolean | `true` | Aktiviert oder deaktiviert die laufende Kopfzeile im Dokument. |
 | `footer` | Boolean | `true` | Aktiviert oder deaktiviert die laufende Fußzeile (inkl. Seitennummerierung). |

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/docs/manual/de/markpublish.yaml

@@ -6,7 +6,7 @@ document:
   summary: "Praxisorientierte Anleitung und Referenz zur Konfiguration, CLI-Bedienung, Theme-Gestaltung und Dokumentenerstellung mit markpublish."
   author: "Frank Winter"
   copyright: "© 2026 Frank Winter"
-  version: "2.3.0"
+  version: "2.3.2"
   date: "auto"
   language: "de"
 

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/docs/manual/en/chapters/04_configuration_guide.md

@@ -41,7 +41,35 @@ Global Table of Contents Settings
 Numbering Rules
 : Settings for automatic numbering (`autonum_pattern`, `autonum_reset`).
 
-#### Custom Metadata Fields
+### Parts (Sections)
+
+A document is organized into high-level sections via `parts:` (e.g., "Main Part", "Case Studies", "Appendices"):
+
+* A document must always be structured using `parts:`; a flat `chapters:` list at the top level is rejected.
+
+* A part groups logically related chapters together.
+
+* By default, a part produces no separate page (`break_before: "none"`): it groups its chapters and passes down its settings, but occupies no page and does not appear in the table of contents. With `break_before: "divider"`, it receives a styled divider page; with `break_before: "page"`, it receives a heading on a fresh page.
+
+* Settings defined at the part level (such as TOC depth or an `autonum_pattern`) are automatically inherited by all chapters contained within.
+
+* Under `parts:`, only declared configuration keys are allowed. Unknown keys (such as `break_befor`) are rejected with fuzzy suggestions to prevent unnoticed misconfigurations.
+
+### Chapters (Chapters)
+
+The `chapters:` list within a part references the actual Markdown content files:
+
+* Each chapter points to its Markdown file (`file:`). Authors can write their Markdown files naturally starting with a `#` heading.
+
+* **`show_title:`** (`true` or `false`, default: `true`) controls whether the file's `#` heading should be rendered on the content page. If a divider page precedes the chapter (`break_before: "divider"`), setting `show_title: false` prevents the title from repeating on the next page – the content page then starts directly with the introductory text or the first subheading.
+
+* Optional keys **`toc_title:`** (for tables of contents and headers) and **`divider_title:`** (for divider pages) allow defining distinct alternative titles (e.g., a concise short form in the table of contents versus an extensive title on the chapter page). When omitted, both inherit the file's `#` heading.
+
+* When generating a divider page (`break_before: "divider"`) or listing the chapter in the table of contents, at least one `#` heading or the corresponding title key (`divider_title` / `toc_title`) must exist; otherwise, the build aborts with an informative error message.
+
+* Chapters can control via `break_before` whether a divider page is generated, a simple page break occurs, or content flows seamlessly.
+
+## Custom Metadata Fields
 
 Under `document:`, **arbitrary custom fields** are permitted beyond the standard keys. They are forwarded to the theme, but are not printed automatically:
 
@@ -76,7 +104,7 @@ Three essential things to keep in mind:
 
 * **Types are preserved.** A `true` is a boolean value, not raw text: the cover page typesets `Yes` or `No` (or `Ja` / `Nein`) depending on the document language. These strings are looked up as `bool_true` and `bool_false` in the i18n cascade.
 
-#### Placeholders in the Text
+## Placeholders in the Text
 
 In Markdown, `{{name}}` inserts a value from `document:`, e.g. `{{author}}`, `{{version}}` or `{{date}}` (the computed date for `"auto"`). This includes custom metadata fields. Values needed only in the text belong under `custom:`. They may be nested there and are addressed with dots:
 
@@ -94,35 +122,58 @@ Contact: {{author}}, {{custom.support_mail}}.
 This document describes {{custom.procedure.name}}.
 ```
 
-Values under `custom` do not reach the theme. A placeholder without a value, including a misspelled one, stops the build and names the file. In code (`` `{{author}}` `` or a code block) the placeholder stays as written; in running text, put a backslash in front: `\{{author}}` gives `{{author}}`.
+If an inserted value is an email address or a URL, it becomes a link, just like text written directly; a placeholder already inside a link keeps that link. Values under `custom` do not reach the theme. A placeholder without a value, including a misspelled one, stops the build and names the file. In code (`` `{{author}}` `` or a code block) the placeholder stays as written; in running text, put a backslash in front: `\{{author}}` gives `{{author}}`.
 
-### Parts (Sections)
+### Loops and Short Names
 
-A document is organized into high-level sections via `parts:` (e.g., "Main Part", "Case Studies", "Appendices"):
-
-* A document must always be structured using `parts:`; a flat `chapters:` list at the top level is rejected.
-
-* A part groups logically related chapters together.
-
-* By default, a part produces no separate page (`break_before: "none"`): it groups its chapters and passes down its settings, but occupies no page and does not appear in the table of contents. With `break_before: "divider"`, it receives a styled divider page; with `break_before: "page"`, it receives a heading on a fresh page.
+`{% for %}` repeats the lines up to `{% endfor %}` for each entry of a group under `custom`, in the order of the YAML file. This gives, for example, a table with one row per role:
 
-* Settings defined at the part level (such as TOC depth or an `autonum_pattern`) are automatically inherited by all chapters contained within.
+```yaml
+document:
+  custom:
+    app:
+      roles:
+        application_owner: {label: "Application owner", name: "A. Sample"}
+        technical_administrator: {label: "Technical administration", name: "B. Example"}
+```
 
-* Under `parts:`, only declared configuration keys are allowed. Unknown keys (such as `break_befor`) are rejected with fuzzy suggestions to prevent unnoticed misconfigurations.
+```markdown
+| Role | Name | Key |
+| :--- | :--- | :--- |
+{% for (role, key) in custom.app.roles %}
+| {{role.label}} | {{role.name}} | {{key}} |
+{% endfor %}
+```
 
-### Chapters (Chapters)
+`{% set %}` gives a long path a short name, valid up to the end of the file (inside a loop, up to the end of that loop):
 
-The `chapters:` list within a part references the actual Markdown content files:
+```markdown
+{% set owner = custom.app.roles.application_owner %}
+Responsible: {{owner.name}}.
+```
 
-* Each chapter points to its Markdown file (`file:`). Authors can write their Markdown files naturally starting with a `#` heading.
+* **Statements stand alone on their line**; the line disappears completely in the build, so a table stays in one piece. Inside a quote or callout, `>` may precede it.
+* **`(role, key)`** also provides the entry's name (`application_owner`); `for role in …` is enough when it is not needed.
+* **Loops can be nested.** A loop's name is valid only inside it; a name must not hide an entry under `document` (`author`, `custom` …).
+* In code and code blocks statements stay as written; in running text, put a backslash in front: `\{% … %}`. Errors such as a missing `{% endfor %}` stop the build and name file and line.
 
-* **`show_title:`** (`true` or `false`, default: `true`) controls whether the file's `#` heading should be rendered on the content page. If a divider page precedes the chapter (`break_before: "divider"`), setting `show_title: false` prevents the title from repeating on the next page – the content page then starts directly with the introductory text or the first subheading.
+## Values from Other Files (`!file`)
 
-* Optional keys **`toc_title:`** (for tables of contents and headers) and **`divider_title:`** (for divider pages) allow defining distinct alternative titles (e.g., a concise short form in the table of contents versus an extensive title on the chapter page). When omitted, both inherit the file's `#` heading.
+Instead of writing a value directly, `!file` loads it from a file or a URL. Both can be mixed freely:
 
-* When generating a divider page (`break_before: "divider"`) or listing the chapter in the table of contents, at least one `#` heading or the corresponding title key (`divider_title` / `toc_title`) must exist; otherwise, the build aborts with an informative error message.
+```yaml
+document:
+  custom:
+    a: "xxx"
+    procedure: !file "../shared/procedure.yaml"
+    purpose: !file "purpose.txt"
+    operator: !file "https://intranet.example/operator.yaml"
+```
 
-* Chapters can control via `break_before` whether a divider page is generated, a simple page break occurs, or content flows seamlessly.
+* **YAML files** (`.yaml`, `.yml`) put their content in place of the reference, so `{{custom.procedure.name}}` reaches into the loaded file. **Any other file** supplies its text as a simple value.
+* **Relative paths** are relative to the file containing the `!file`, or to the URL it was loaded from.
+* **Nested:** a loaded YAML file may itself contain `!file`. The same file may appear in several places; a reference leading back to itself through the chain stops the build.
+* `!file` works anywhere in the configuration, not only under `custom`. A URL request waits at most 10 seconds.
 
 ---
 

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/docs/manual/en/chapters/07_appendix_yaml_spec.md

@@ -19,7 +19,7 @@ The `document:` section defines global metadata, layout switches, table of conte
 | `date` | String | `"auto"` | Document date. Set to `"auto"` or `"today"` to use current date. |
 | `version` | String | `None` | Version identifier (e.g., `"2.0.0"`). Only printed when explicitly set. |
 | `language` | String | *(System language)* | ISO language code (e.g., `"en"` or `"de"`). Governs hyphenation and UI strings. |
-| `custom` | Mapping | `{}` | Own values for placeholders in the text (`{{custom.a.b}}`), may be nested. See *Placeholders in the Text*. |
+| `custom` | Mapping | `{}` | Own values for placeholders in the text (`{{custom.a.b}}`), may be nested. See *Placeholders in the Text*. Single values or groups can be loaded with `!file`. |
 | `cover` | Boolean | `false` | Controls whether a styled cover page is generated. |
 | `header` | Boolean | `true` | Enables or disables running headers throughout the document. |
 | `footer` | Boolean | `true` | Enables or disables running footers (including page numbering). |

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/docs/manual/en/markpublish.yaml

@@ -6,7 +6,7 @@ document:
   summary: "Practical guide and reference for configuration, CLI usage, theme design, and document publishing with markpublish."
   author: "Frank Winter"
   copyright: "© 2026 Frank Winter"
-  version: "2.3.0"
+  version: "2.3.2"
   date: "auto"
   language: "en"
 

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/locale/de.yaml

@@ -167,8 +167,18 @@ err.config.toc_bool: "{key_path} nimmt keine Wahrheitswerte. Schreiben Sie 'none
 err.config.toc_value: "{key_path} kennt {allowed} oder eine Tiefe als Zahl (war: {value})."
 err.config.custom_value: "{key_path} muss ein einfacher Wert (Text, Zahl) oder eine Gruppe weiterer Werte sein."
 err.config.custom_key: "{key_path}: Namen unter custom bestehen nur aus Buchstaben, Ziffern, '_' und '-'."
+err.config.file_ref_missing: "!file \"{src}\": Datei nicht gefunden ({path})."
+err.config.file_ref_cycle: "!file \"{src}\": Zyklischer Verweis, {path} lädt sich über diese Kette selbst nach."
+err.config.file_ref_url: "!file \"{src}\": Abruf fehlgeschlagen ({reason})."
 err.variable.unknown: "Platzhalter {{{{{name}}}}} in {file} hat keinen Wert. Verfügbar sind die Angaben unter document (z. B. {{{{author}}}}) und custom.* ."
 err.variable.document_field: "Platzhalter {{{{{name}}}}} in {file} hat keinen Wert. In den Angaben unter document sind nur Werte aus custom.* erlaubt (z. B. {{{{custom.verfahren.name}}}})."
+err.statement.syntax: "{file}, Zeile {line}: {{% {text} %}} ist keine bekannte Anweisung. Möglich sind {{% for name in custom.a %}}, {{% for (name, key) in custom.a %}}, {{% endfor %}} und {{% set name = custom.a.b %}}."
+err.statement.inline: "{file}, Zeile {line}: Eine Anweisung {{% … %}} muss allein in ihrer Zeile stehen. Als Text schreiben Sie \\{{% … %}}."
+err.statement.unclosed: "{file}, Zeile {line}: Zu diesem {{% for %}} fehlt das {{% endfor %}}."
+err.statement.stray_end: "{file}, Zeile {line}: {{% endfor %}} ohne vorangehendes {{% for %}}."
+err.statement.unknown_path: "{file}, Zeile {line}: {path} hat keinen Wert."
+err.statement.not_group: "{file}, Zeile {line}: {path} ist ein einzelner Wert, keine Gruppe; {{% for %}} kann nicht darüber laufen."
+err.statement.reserved: "{file}, Zeile {line}: Der Name {name} ist schon eine Angabe unter document. Wählen Sie einen anderen Namen."
 err.config.toc_depth: "{key_path} braucht eine Tiefe ab 1 (war: {value}). Für 'kommt nicht vor' schreiben Sie 'none'."
 err.config.toc_kind: "{key_path} kennt 'none', 'full' oder eine Tiefe als Zahl (war: {value})."
 err.config.document_unknown: |

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/locale/en.yaml

@@ -170,8 +170,18 @@ err.config.toc_bool: "{key_path} takes no boolean. Write 'none', 'full' or a dep
 err.config.toc_value: "{key_path} takes {allowed} or a depth as a number (was: {value})."
 err.config.custom_value: "{key_path} must be a simple value (text, number) or a group of further values."
 err.config.custom_key: "{key_path}: names under custom consist only of letters, digits, '_' and '-'."
+err.config.file_ref_missing: "!file \"{src}\": file not found ({path})."
+err.config.file_ref_cycle: "!file \"{src}\": circular reference, {path} loads itself through this chain."
+err.config.file_ref_url: "!file \"{src}\": retrieval failed ({reason})."
 err.variable.unknown: "Placeholder {{{{{name}}}}} in {file} has no value. Available are the entries under document (e.g. {{{{author}}}}) and custom.* ."
 err.variable.document_field: "Placeholder {{{{{name}}}}} in {file} has no value. The entries under document may only use values from custom.* (e.g. {{{{custom.verfahren.name}}}})."
+err.statement.syntax: "{file}, line {line}: {{% {text} %}} is not a known statement. Available are {{% for name in custom.a %}}, {{% for (name, key) in custom.a %}}, {{% endfor %}} and {{% set name = custom.a.b %}}."
+err.statement.inline: "{file}, line {line}: a statement {{% … %}} must stand alone on its line. To show it as text, write \\{{% … %}}."
+err.statement.unclosed: "{file}, line {line}: this {{% for %}} has no {{% endfor %}}."
+err.statement.stray_end: "{file}, line {line}: {{% endfor %}} without a preceding {{% for %}}."
+err.statement.unknown_path: "{file}, line {line}: {path} has no value."
+err.statement.not_group: "{file}, line {line}: {path} is a single value, not a group; {{% for %}} cannot loop over it."
+err.statement.reserved: "{file}, line {line}: the name {name} is already an entry under document. Choose another name."
 err.config.toc_depth: "{key_path} needs a depth of at least 1 (was: {value}). For 'does not appear' write 'none'."
 err.config.toc_kind: "{key_path} takes 'none', 'full' or a depth as a number (was: {value})."
 err.config.document_unknown: |

{markpublish-2.3.0 → markpublish-2.3.2}/src/markpublish/markdown/engine.py

@@ -34,7 +34,12 @@ from markpublish.markdown.typst_serializer import (
     html_to_tree,
     process_tree_headings_and_toc,
 )
-from markpublish.markdown.variables import build_variables, protect_escapes, substitute_tree
+from markpublish.markdown.variables import (
+    build_variables,
+    expand_statements,
+    protect_escapes,
+    substitute_tree,
+)
 from markpublish.ui import t
 
 #: Namen der String-Extensions. Der GitHubAlertsExtension wird pro Sprache
@@ -555,6 +560,7 @@ class MarkdownPipeline:
         # Convert markdown to HTML via python-markdown (all extensions active)
         if raw_md and doc_cfg:
             raw_md = protect_escapes(raw_md)
+            raw_md = expand_statements(raw_md, build_variables(doc_cfg), chapter_cfg.file or "")
         raw_html = self.engine.convert(raw_md) if raw_md else ""
 
         # Parse HTML into ElementTree and process headings / numbering directly in the AST