Improve use of diagrams

Author: dannyadair

docs/configuration.md

@@ -19,12 +19,22 @@ project/
 
 ## Configuration Workflow
 
+For every page, your main configuration (for all documents), document configuration (for all pages of this document) and the page configuration are merged to form the context provided to your page template. 
+
 ```mermaid
-graph TD
-    Main[Main config] -->|merge| Document[Document config]
-    Document -->|merge| Page[Page config]
-    Template[SVG Template] -.- Page
-    Template -->|render| SVG[SVG Page]
+flowchart TD
+    subgraph Configuration
+        Main[YAML Main Config] -->|inherits| Doc[YAML Document Config]
+        Doc -->|inherits| Page[YAML Page Config]
+    end
+
+    subgraph Page Processing
+        Template[SVG Template]
+        Page -->|context| Render[Template Rendering]
+        Template -->|jinja2| Render
+        Render -->|output| SVG[SVG File]
+        SVG -->|cairosvg| PDF[PDF File]
+    end
 ```
 
 ## Main Configuration File

docs/overview.md

@@ -13,23 +13,76 @@ documents with minimal effort.
 - **Custom Processing**: Extend the processing workflow with Python
 - **PDF Compression**: Optional compression of final PDFs
 
+## Quickstart
+
+For a quick introduction, see the [README](../README.md).
+
+## Workflow
+
+### From configuration to PDF documents
+
+Your main configuration defines which documents to create.<br>Each document configuration defines which pages make up the document.
+
 ```mermaid
-graph TD
-    Main[Main config] -->|merge| Document[Document config]
-    Document -->|merge| Page[Page config]
-    Template[SVG Template] -.- Page
-    Template -->|render| SVG[SVG Page]
-    SVG -->|convert| PDF[PDF Page]
+flowchart TD
+    Main[YAML Main Config] -->|document 1| Doc1[Document Processing]
+    Main -->|document 2| Doc2[Document Processing]
+
+    subgraph Document1[Document]
+        Doc1 -->|page 1| Page1[Page Processing]
+        Doc1 -->|page 2| Page2[Page Processing]
+        Doc1 -->|page n| PageN[Page Processing]
+        
+        Page1 --> PDF1[PDF File Page 1]
+        Page2 --> PDF2[PDF File Page 2]
+        PageN --> PDFN[PDF File Page ...]
+
+        PDF1 --> PDF[PDF Pages]
+        PDF2 --> PDF[PDF Pages]
+        PDFN --> PDF[PDF Pages]
+
+        PDF -->|combine| PDFDocument[PDF Document]
+    end
+
+    Doc2 -->|pages| Doc2PageProcessing[...]
+    Doc2PageProcessing --> Doc2PageFile[...]
+    Doc2PageFile --> Doc2Pages[...]
+    Doc2Pages -->|combine| Doc2PDFDocument[PDF Document]
+```
 
+### Inheriting common values
+
+Settings in the main configuration are available to all documents.<br>Settings in a document configuration are available to all of its pages.<br>Each page configuration can hold page-specific settings/content, so that the template of page is only responsible for layout/design.
+
+```mermaid
+flowchart TD
+    subgraph Configuration
+        Main[YAML Main Config] -->|inherits| Doc[YAML Document Config]
+        Doc -->|inherits| Page[YAML Page Config]
+    end
+
+    subgraph Page Processing
+        Template[SVG Template]
+        Page -->|context| Render[Template Rendering]
+        Template -->|jinja2| Render
+        Render -->|output| SVG[SVG File]
+        SVG -->|cairosvg| PDF[PDF File]
+    end
 ```
 
+### Pages make up a document
+
+After each page template was rendered and the resulting SVG file converted to PDF, these page PDFs are combined to create the document.<br>This may optionally get compressed for a nice end result.
+
 ```mermaid
-graph LR
-    Page1[PDF Page 1] -->|combine| Document[PDF Document]
-    Page2[PDF Page 2] -->|combine| Document
-    PageN[PDF Page ...] -->|combine| Document
-    Document -.->|compress| Compressed[PDF Document compressed]
-    linkStyle 3 stroke-dasharray: 5 5
+flowchart LR
+    subgraph Document Creation
+        Page1[PDF File Page 1] -->|combine| Document[PDF Document]
+        Page2[PDF File Page 2] -->|combine| Document
+        PageN[PDF File Page ...] -->|combine| Document
+        Document -.->|ghostscript| Compressed[PDF Document compressed]
+        linkStyle 3 stroke-dasharray: 5 5
+    end
 ```
 
 ## Documentation
@@ -38,10 +91,6 @@ graph LR
 - [Document Variants](variants.md) - Create multiple versions of a document
 - [Custom Processing](custom_processing.md) - Extend the processing workflow
 
-## Quickstart
-
-For a quick introduction, see the [README](../README.md).
-
 ## Examples
 
 See the [examples](examples) directory: