docs: replace images with text in mode-of-operation (fixes #31)

docs/_static/custom.js

@@ -0,0 +1,20 @@
+/**
+ * Fix for mermaid diagram SVG height issue.
+ * 
+ * The mermaid extension generates inline <style> with fixed height (500px)
+ * which causes large gaps above and below diagrams.
+ * 
+ * CSS cannot override this because the inline style loads after custom.css.
+ * MutationObserver watches for DOM changes and fixes the height dynamically.
+ */
+const observer = new MutationObserver(function(mutations) {
+    const svgs = document.querySelectorAll('.mermaid-container > pre > svg');
+    svgs.forEach(function(svg) {
+        svg.style.height = 'auto';
+    });
+});
+
+observer.observe(document.body, {
+    childList: true,
+    subtree: true
+});

docs/conf.py

@@ -231,6 +231,11 @@
 # NOTE: If undefined, set to None, or empty,
 #       the sphinx_reredirects extension will be disabled.
 
+html_static_path = ['_static']
+# Custom JS to fix mermaid diagram height issue
+# See: _static/custom.js
+html_js_files = ['custom.js']
+
 redirects = {}
 
 
@@ -266,10 +271,15 @@
 #       substitution, deflist, linkify
 
 myst_enable_extensions = set(
-    ["substitution", "deflist", "linkify", "tasklist", "attrs_inline"]
+    ["substitution", "deflist", "linkify", "tasklist", "attrs_inline", "colon_fence"]
 )
 
 
+# Fix: Tell MyST to treat "mermaid" code blocks as a directive, 
+# preventing the "Pygments lexer name 'mermaid' is not known" warning.
+myst_fence_as_directive = ["mermaid"]
+
+
 # Custom Sphinx extensions; see
 # https://www.sphinx-doc.org/en/master/usage/extensions/index.html
 
@@ -295,6 +305,7 @@
     "sphinx_last_updated_by_git",
     "sphinx.ext.intersphinx",
     "sphinx_sitemap",
+    "sphinxcontrib.mermaid",
 ]
 
 # Excludes files or directories from processing

docs/explanation/mode-of-operation.md

@@ -2,97 +2,48 @@
 
 # How Chisel works
 
-The purpose of Chisel is to create a minimal Ubuntu root file system comprising
-only the application and its runtime dependencies. Chisel is especially useful
-for developers who are looking to create minimal and distroless-like container
-images.
-
 Chisel uses the {{cut_cmd}} to _slice_ Ubuntu packages, as depicted in the workflow below:
 
-<table style="width: 100%;">
-  <colgroup>
-    <col style="width: 45%;">
-    <col style="width: 55%;">
-  </colgroup>
-
-<!-- MO 1 -->
-  <tr>
-    <td>
-
-```{image} /_static/MO-1.svg
-  :align: center
-  :alt: Read and parse chisel-releases
-```
-
-</td>
-    <td>
-
-Chisel fetches, reads and validates the {ref}`chisel-release<chisel-releases_ref>`.
-This includes parsing the {ref}`chisel_yaml_ref` and {ref}`slice 
-definitions<slice_definitions_ref>` while validating the release and checking for conflicting paths across packages.
-
-</td>
-  </tr>
-
-
-<!-- MO 2 -->
-  <tr>
-    <td>
-
-```{image} /_static/MO-2.svg
-  :align: center
-  :alt: Talk to archives and fetch packages
-```
-
-</td>
-    <td>
-
-Chisel talks to the {ref}`chisel_yaml_format_spec_archives` directly.
-It fetches, validates and parses their `InRelease` files.
-It then resolves which archive holds the **requested** packages and fetches
-the corresponding package tarballs.
-
-</td>
-  </tr>
-
-<!-- MO 3 -->
-  <tr>
-    <td>
-
-```{image} /_static/MO-3.svg
-  :align: center
-  :alt: Install package slices
-```
-
-</td>
-    <td>
-
-Chisel groups and merges all slice definitions per package. Then,
-for every package, it extracts the **specified slices' paths** into
-the provided root file system.
-
-</td>
-  </tr>
-
-<!-- MO 4 -->
-  <tr>
-    <td>
-
-```{image} /_static/MO-4.svg
-  :align: center
-  :alt: Run mutation scripts
-```
-
-</td>
-    <td>
-
-Chisel then runs the {{mutation_scripts}}. Only the
-{ref}`mutable<slice_definitions_format_slices_contents_mutable>` files may be
-modified at this stage. Finally, the files specified with
-{ref}`until:mutate<slice_definitions_format_slices_contents_until>` are
-removed from the provided root file system.
-
-
-</td>
-  </tr>
-</table>
+```{list-table}
+:widths: 45 55
+:header-rows: 0
+:class: align-middle
+
+* - ```mermaid
+    graph TD
+        step1{{1. Read and parse chisel-releases}}
+        style step1 fill:#a81c1c,stroke:#333,stroke-width:1px,color:white
+    ```
+  - Chisel fetches, reads and validates the {ref}`chisel-release<chisel-releases_ref>`.
+    This includes parsing the {ref}`chisel_yaml_ref` and {ref}`slice 
+    definitions<slice_definitions_ref>` while validating the release and checking for conflicting paths across packages.
+
+* - ```mermaid
+    graph TD
+        step2{{2. Talk to Ubuntu archives<br>and fetch packages}}
+        style step2 fill:#a81c1c,stroke:#333,stroke-width:1px,color:white
+    ```
+  - Chisel talks to the {ref}`chisel_yaml_format_spec_archives` directly.
+    It fetches, validates and parses their `InRelease` files.
+    It then resolves which archive holds the **requested** packages and fetches
+    the corresponding package tarballs.
+
+* - ```mermaid
+    graph TD
+        step3{{3. Install only the specified<br>files from packages}}
+        style step3 fill:#a81c1c,stroke:#333,stroke-width:1px,color:white
+    ```
+  - Chisel groups and merges all slice definitions per package. Then,
+    for every package, it extracts the **specified slices' paths** into
+    the provided root file system.
+
+* - ```mermaid
+    graph TD
+        step4{{4. Run mutation scripts and<br>remove temporary files}}
+        style step4 fill:#a81c1c,stroke:#333,stroke-width:1px,color:white
+    ```
+  - Chisel then runs the {{mutation_scripts}}. Only the
+    {ref}`mutable<slice_definitions_format_slices_contents_mutable>` files may be
+    modified at this stage. Finally, the files specified with
+    {ref}`until:mutate<slice_definitions_format_slices_contents_until>` are
+    removed from the provided root file system.

docs/requirements.txt

@@ -26,6 +26,7 @@ packaging
 sphinxcontrib-svg2pdfconverter[CairoSVG]
 sphinx-last-updated-by-git
 sphinx-sitemap
+sphinxcontrib-mermaid
 
 # Vale dependencies
 rst2html