Improve documentation on graphics and attachments

- Restructure content slightly
- Add docu on how to resize graphics on Linux using ImageMagick
- Add docu on alignment of graphics
- Add docu on resizing graphics
- Add used plugin for videos

doc.zih.tu-dresden.de/docs/contrib/content_rules.md

@@ -41,7 +41,7 @@ or via [e-mail](mailto:hpc-support@tu-dresden.de).
 * Use spaces (not tabs) both in Markdown files and in `mkdocs.yml`.
 * Respect the line length limit of 100 characters (exception: links).
 * Do not add large binary files or high-resolution images to the repository (cf.
-   [adding images and attachments](#graphics-and-attachments)).
+   [adding images and attachments](#graphics-and-videos)).
 * [Admonitions](#special-feature-admonitions) may be actively used for longer code examples,
    warnings, tips, important information, etc.
 * Respect the [writing style](#writing-style) and the rules for
@@ -50,6 +50,7 @@ or via [e-mail](mailto:hpc-support@tu-dresden.de).
     * Use [syntax highlighting and appropriate prompts](#code-blocks-and-command-prompts).
     * Respect [data privacy](#data-privacy-and-generic-names).
     * Stick to the [rules on optional and required arguments](#code-styling-rules).
+* Save attachments, graphics and videos within the respective `misc` subdirectory.
 
 ## Detailed Overview
 
@@ -131,86 +132,120 @@ Markdown dialects.
 Further tips can be found on this
 [cheat sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
 
-#### Graphics and Attachments
+#### Attachments
 
-Please use images and graphics for illustration purposes and to improve comprehensibility.
+Of course, you can provide attachments in sections and pages.
+Such attachment documents may contain information that are more detailed and go far beyond the
+scope of the compendium, e.g. user manuals for application-specific software.
+
+Save attachments within the `misc` subdirectory of the corresponding section.
+
+!!! note "Syntax for attachments"
+
+    The syntax for attachments is the very same as for links. As the attachment is within the `misc`
+    subdirectory, you can refer to it as local file.
+
+    ```markdown
+    [<description>](misc/<attachment_name>.pdf)
+    ```
+
+    Since the `<descripton>` is rendered as link text, you should choose a clear and precise text.
+
+#### Graphics and Videos
+
+Please use graphics and videos for illustration purposes and to improve comprehensibility.
 All graphics and attachments are saved within `misc` directory of the respective subdirectory in
 `docs`.
-For video attachments please use either webm or mp4 format.
+For video attachments please use either webm or mp4 format. We make use of the
+[mkdocs-video extension](https://github.com/soulless-viewer/mkdocs-video).
 
-!!! example "Syntax"
+!!! note "Syntax for graphics and videos"
 
-    The syntax to insert a graphic or attachment into a page is
+    The syntax to insert a **graphic** into a page is
 
     ```markdown
     ![Alternative text](misc/graphics_file.png)
-    {: align="center"}
     ```
 
-    The syntax to insert a video attachment into a page is
+    The syntax to insert a **video** attachment into a page is
 
     ```html
     ![type:video](misc/terminate-virtual-desktop-dcv.mp4)
     ```
 
-The attribute `align` is optional. By default, graphics are left-aligned. **Note:** It is crucial to
-have `{: align="center"}` on a new line.
 It is possible to add captions for tables and figures using `{: summary="This is a table caption"}`.
 The `summary` and `align` parameters can be combined as well:
 `{: summary="This is a table caption" align="top"}`.
 
+##### Resizing and Alignment of Graphics
+
+In general, graphics and images should be added to the repository with the desired size.
+
 !!! warning
 
     Do not add large binary files or high-resolution images to the repository. See this valuable
     document for [image optimization](https://web.dev/fast/#optimize-your-images).
 
-#### Alignment and Sizing of Graphics
+We recommend the well-know Linux package [ImageGraphics](https://imagemagick.org/) for resizing
+graphics.
+
+!!! example "Resize image using ImageMagick"
+
+    The command
+
+    ```console
+    marie@login$ magick cluster.jpeg -resize 600 cluster_600.jpeg
+    ```
+
+    will size the graphic `cluster.jpeg` to a width of 600 pixels keeping the aspect ratio.
+    Depending on the resolution of the original file, the resulting file can be way smaller in terms
+    of memory foot print.
 
-!!! note "Scale graphics once"
+Nevertheless you can explicitly specify the size a graphic. The syntax is as follows
+
+```markdown
+![Alternative text](misc/graphics_file.png){: style="width:150px"}
+```
 
-    Graphics and images should be added to the repository with the desired size. If you add a file
-    If you add a graphic that is too large, it is implicitly converted to a suitable size. This
-    conversion happens every time the documentation is built, i.e., every time the CI/CD pipeline is
-    run. Over the project's lifetime, this will happen many thousands of times.
+By default, graphics are left-aligned. In most cases, this is not elegant and you probably wish to
+center-align your graphics. **Alignment** of graphics can be controlled via the `{: align=<value>}`
+attribute. Possible values are `left`, `right` and `center`. **Note:** It is crucial to
+have `{: align=center}` on a new line and the value without quotation marks.
 
-    While MkDocs scales images to fit the content width, it doesn’t compress images or reduce file
-    sizes automatically. Therefore, it’s still essential to optimize image sizes and resolutions
-    before uploading to ensure good performance.
+Resize and alignment specification can be combined as depicted in the following example.
 
-!!! example "Scale image to 150px width"
+!!! example "Resize image to 150px width and specify alignment"
 
-    The following Markdown syntax will scale the image of the beautiful
-    [cluster `Barnard`](../jobs_and_resources/hardware_overview.md#barnard) to a width of 150
-    pixels and height of 150 pixels.
+    The three tabs show the Markdown syntax to resize the image of the beautiful
+    [cluster `Barnard`](../jobs_and_resources/hardware_overview.md#barnard) to a height of 150
+    pixels keeping the aspect ratio and left, center and right-align it, respectively.
 
-    === "Scale"
+    === "Scale and default-align"
 
         ```markdown
-        ![Beauty Barnard](misc/barnard.jpeg){: style="height:150px;width:150px"}
+        ![Beauty Barnard](misc/barnard.jpeg){: style="height:150px"}
         ```
 
-        ![Beauty Barnard](misc/barnard.jpeg){: style="height:150px;width:150px"}
+        ![Beauty Barnard](misc/barnard.jpeg){: style="height:150px"}
 
-    === "Align=center"
+    === "Scale and center-align"
 
-        Now let's scale the very same image to 150 pixel width keeping aspect ratio and center align it.
         ```markdown
-        ![Beauty Barnard](misc/barnard.jpeg){: style="height:150px;width:150px"}
+        ![Beauty Barnard](misc/barnard.jpeg){: style="height:150px"}
         {: align="center"}
         ```
 
-        ![Beauty Barnard](misc/barnard.jpeg){: style="width:150px"}
+        ![Beauty Barnard](misc/barnard.jpeg){: style="height:150px"}
         {: align="center"}
 
-    === "Align=right"
+    === "Scale and right-align"
 
-        Now let's scale the very same image to 150 pixel width keeping aspect ratio and center align it.
         ```markdown
-        ![Beauty Barnard](misc/barnard.jpeg){: style="width:150px"}
+        ![Beauty Barnard](misc/barnard.jpeg){: style="height:150px"}
         {: align="right"}
         ```
 
-        ![Alternative text](misc/barnard.jpeg){: style="width:150px"}
+        ![Alternative text](misc/barnard.jpeg){: style="height:150px"}
         {: align="right"}
 
 #### Special Feature: Admonitions