From 3713a0fa390dfce23f5d4425e8fe52c72eb1b2bd Mon Sep 17 00:00:00 2001
From: Martin Schroschk <martin.schroschk@tu-dresden.de>
Date: Mon, 4 Nov 2024 12:55:48 +0100
Subject: [PATCH] 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
---
.../docs/contrib/content_rules.md | 103 ++++++++++++------
1 file changed, 69 insertions(+), 34 deletions(-)
diff --git a/doc.zih.tu-dresden.de/docs/contrib/content_rules.md b/doc.zih.tu-dresden.de/docs/contrib/content_rules.md
index e2fbb6cc5..c456848aa 100644
--- a/doc.zih.tu-dresden.de/docs/contrib/content_rules.md
+++ b/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
- {: 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
```
-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
+{: 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
- {: style="height:150px;width:150px"}
+ {: style="height:150px"}
```
- {: style="height:150px;width:150px"}
+ {: 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
- {: style="height:150px;width:150px"}
+ {: style="height:150px"}
{: align="center"}
```
- {: style="width:150px"}
+ {: 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
- {: style="width:150px"}
+ {: style="height:150px"}
{: align="right"}
```
- {: style="width:150px"}
+ {: style="height:150px"}
{: align="right"}
#### Special Feature: Admonitions
--
GitLab