Merge branch 'contribute_graphics' into 'preview'

Add documentation on how to scale and align graphics

See merge request !1149

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,39 +132,126 @@ 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_file_name>)
+    ```
+
+    Since the `<description>` is rendered as link text, you should choose a clear and precise text:
+
+    ```markdown
+    [slides of HPC introduction](misc/HPC-Introduction.pdf)
+    ```
+
+#### 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).
 
+We recommend the well-know Linux package [ImageMagick](https://imagemagick.org/) for resizing
+graphics.
+
+!!! example "Resize image using ImageMagick"
+
+    The command
+
+    ```console
+    marie@local$ magick cluster.jpeg -resize 600 cluster_600.jpeg
+    ```
+
+    will resize 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.
+
+Nevertheless you can explicitly specify the size a graphic. The syntax is as follows
+
+```markdown
+![Alternative text](misc/graphics_file.png){: style="width:150px"}
+```
+
+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.
+
+Resize and alignment specification can be combined as depicted in the following example.
+
+!!! example "Resize image to 150px width and specify alignment"
+
+    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 and default-align"
+
+        ```markdown
+        ![Beauty Barnard](misc/barnard.jpeg){: style="height:150px"}
+        ```
+
+        ![Beauty Barnard](misc/barnard.jpeg){: style="height:150px"}
+
+    === "Scale and center-align"
+
+        ```markdown
+        ![Beauty Barnard](misc/barnard.jpeg){: style="height:150px"}
+        {: align="center"}
+        ```
+
+        ![Beauty Barnard](misc/barnard.jpeg){: style="height:150px"}
+        {: align="center"}
+
+    === "Scale and right-align"
+
+        ```markdown
+        ![Beauty Barnard](misc/barnard.jpeg){: style="height:150px"}
+        {: align="right"}
+        ```
+
+        ![Alternative text](misc/barnard.jpeg){: style="height:150px"}
+        {: align="right"}
+
 #### Special Feature: Admonitions
 
 [Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/), also known as

doc.zih.tu-dresden.de/wordlist.aspell

@@ -175,6 +175,7 @@ icc
 icpc
 iDataPlex
 ifort
+ImageMagick
 ImageNet
 img
 InfiniBand