Merge pull request #6834 from umbraco/images

Updated Images style guide article

Author: eshanrnh

contributing/documentation/style-guide/images.md

@@ -0,0 +1,76 @@
+---
+description: >-
+  Learn how to add images to the documentation.
+---
+
+# Images
+
+Images should be stored in an `images` directory next to the `.md` file referencing them, using relative paths. Use descriptive alt text and captions to ensure accessibility and Search Engine Optimization (SEO) benefits. Optimize images for the web to improve page load times.
+
+## General Guidelines
+
+* Maximum image width: **800px**.
+* Supported formats: `png`, `jpg`, `gif` (use the most efficient compression available).
+* Prohibited formats: `bmp`, `tiff`, `swf` (Flash)
+
+## Folder Structure
+
+If images are used, these must be stored in an `images` directory next to the `.md` file referencing them using relative paths.
+
+Maintain a clear and consistent directory structure:
+
+```plaintext
+/topic               # Main documentation directory
+│── README.md        # Main content file
+│── another-page.md  # Another markdown file
+│── /images          # Image storage
+│   ├── image1.png
+│   ├── image2.jpg
+│
+└── /subtopic        # Subdirectory for related content
+    │── README.md
+    │── topic.md
+    │── another-topic.md  
+    │── /images      # Subdirectory for subtopic images
+        ├── image3.png
+```
+
+## Adding images in Markdown
+
+Use the following markdown syntax to insert images:
+
+### Image with Caption
+
+```md
+![Caption](../images/sample.png)
+```
+
+### Image with Alt Text (Markdown/GitHub)
+
+```md
+![Alt text describing the image](images/img.png)
+```
+
+### Image with Alt Text
+
+Images added through the GitBook platform are automatically inserted using HTML syntax, as shown in the example below:
+
+```html
+<figure><img src="../images/sample.png" alt="The New Backoffice"></figure>
+```
+
+However, when contributing to the documentation via GitHub, it is recommended to use Markdown for images instead:
+
+```md
+![The New Backoffice](../images/sample.png)
+```
+
+{% hint style="info" %}
+Always provide alt text or a caption to describe the image’s purpose and content.
+{% endhint %}
+
+## Best Practices
+
+* Use clear and relevant filenames. For example: `dashboard-view.png` instead of `image1.png`.
+* Avoid excessive text in images. If text is necessary, provide a description above or below the image in the documentation.
+* Use SVG format for diagrams and icons where possible to ensure scalability.

contributing/documentation/style-guide/markdown-conventions.md

@@ -8,20 +8,6 @@ The Umbraco Documentation uses Markdown for all articles.
 
 In this article you can learn how we Markdown for different elements on our documentation.
 
-## Images
-
-Images are linked using relative paths to `.md` pages.
-
-The following sample adds an image, `img.png`, located in an `images` folder:
-
-```markdown
-![My Image Alt Text](images/img.png)
-```
-
-{% hint style="info" %}
-Make sure to add a descriptive image text that presents the user with the same information as the image provides.
-{% endhint %}
-
 ## Links
 
 In the following you will find a few examples of different links.

contributing/documentation/style-guide/structure.md

@@ -28,15 +28,3 @@ Each directory must have a `README.md` file which will act as a landing page for
 All file and directory names need to be small-caps in order to be synced properly with GitBook.
 
 If an article is not a landing page, we recommend using the title of the article as the file name.
-
-## Images
-
-Images are stored and linked using relative paths to .md pages, and should by convention always be in an `images` directory. To add an image to `/documentation/reference/partials/renderviewpage.md` you link it like so:
-
-```markdown
-![My Image Alt Text](images/img.png)
-```
-
-And store the image as `/documentation/reference/partials/images/img.png`
-
-Images can have a maximum width of **800px**. Please always try to use the most efficient compression, `gif` or `png`. No `bmp`, `tiff` or `swf` (Flash).