From d00201edde879ef1d2449bf6a65e87a8f7e6feaf Mon Sep 17 00:00:00 2001 From: Esha Noronha Date: Thu, 30 Jan 2025 14:53:15 +0100 Subject: [PATCH 1/8] Updated Images style guide article --- .../documentation/style-guide/images.md | 70 +++++++++++++++++++ .../style-guide/markdown-conventions.md | 14 ---- .../documentation/style-guide/structure.md | 12 ---- 3 files changed, 70 insertions(+), 26 deletions(-) create mode 100644 contributing/documentation/style-guide/images.md diff --git a/contributing/documentation/style-guide/images.md b/contributing/documentation/style-guide/images.md new file mode 100644 index 00000000000..d57076145a1 --- /dev/null +++ b/contributing/documentation/style-guide/images.md @@ -0,0 +1,70 @@ +--- +description: >- + Learn how to add images and its folder structure. +--- + +# Images + +Images should be stored in an `images` or `assets` 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` or `assets` 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 + +```markdown +![Caption](../images/sample.png) +``` + +* Image with Alt Text (Markdown/GitHub): + +```markdown +![Alt text describing the image](images/img.png) +``` + +* Image with Alt Text (GitBook) + +```html +
The New Backoffice
+``` + +{% 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. diff --git a/contributing/documentation/style-guide/markdown-conventions.md b/contributing/documentation/style-guide/markdown-conventions.md index 443cde7a172..0bc910dd211 100644 --- a/contributing/documentation/style-guide/markdown-conventions.md +++ b/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. diff --git a/contributing/documentation/style-guide/structure.md b/contributing/documentation/style-guide/structure.md index f7dddfa4761..40091eb2643 100644 --- a/contributing/documentation/style-guide/structure.md +++ b/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). From 19fa1d0cfcb243f559cf11e129667891a8aa4dcd Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 3 Feb 2025 09:26:16 +0100 Subject: [PATCH 2/8] Update contributing/documentation/style-guide/images.md Co-authored-by: sofietoft --- contributing/documentation/style-guide/images.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/documentation/style-guide/images.md b/contributing/documentation/style-guide/images.md index d57076145a1..6570d239ee5 100644 --- a/contributing/documentation/style-guide/images.md +++ b/contributing/documentation/style-guide/images.md @@ -1,6 +1,6 @@ --- description: >- - Learn how to add images and its folder structure. + Learn how to add images to the documentation. --- # Images From d330bc911439e9a3370742968ff10506105e9dbd Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 3 Feb 2025 09:26:23 +0100 Subject: [PATCH 3/8] Update contributing/documentation/style-guide/images.md Co-authored-by: sofietoft --- contributing/documentation/style-guide/images.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/documentation/style-guide/images.md b/contributing/documentation/style-guide/images.md index 6570d239ee5..e43c4b29a5e 100644 --- a/contributing/documentation/style-guide/images.md +++ b/contributing/documentation/style-guide/images.md @@ -5,7 +5,7 @@ description: >- # Images -Images should be stored in an `images` or `assets` 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. +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 From 8c1b5d8ede3a7b0d27cf64f1fd4e0aa2dbc6ffbc Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 3 Feb 2025 09:26:33 +0100 Subject: [PATCH 4/8] Update contributing/documentation/style-guide/images.md Co-authored-by: sofietoft --- contributing/documentation/style-guide/images.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/contributing/documentation/style-guide/images.md b/contributing/documentation/style-guide/images.md index e43c4b29a5e..013033bb6ac 100644 --- a/contributing/documentation/style-guide/images.md +++ b/contributing/documentation/style-guide/images.md @@ -10,9 +10,7 @@ Images should be stored in an `images` directory next to the `.md` file referenc ## 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 From faa79acaeb2c45be463e2b185278f37060a608b5 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 3 Feb 2025 09:26:40 +0100 Subject: [PATCH 5/8] Update contributing/documentation/style-guide/images.md Co-authored-by: sofietoft --- contributing/documentation/style-guide/images.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/documentation/style-guide/images.md b/contributing/documentation/style-guide/images.md index 013033bb6ac..b32f0755266 100644 --- a/contributing/documentation/style-guide/images.md +++ b/contributing/documentation/style-guide/images.md @@ -15,7 +15,7 @@ Images should be stored in an `images` directory next to the `.md` file referenc ## Folder Structure -If images are used, these must be stored in an `images` or `assets` directory next to the `.md` file referencing them using relative paths. +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: From 15673b7af48e54a6d1fa2d215a4e88affef5ea2d Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 3 Feb 2025 09:26:48 +0100 Subject: [PATCH 6/8] Update contributing/documentation/style-guide/images.md Co-authored-by: sofietoft --- contributing/documentation/style-guide/images.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/documentation/style-guide/images.md b/contributing/documentation/style-guide/images.md index b32f0755266..da2bf128a6b 100644 --- a/contributing/documentation/style-guide/images.md +++ b/contributing/documentation/style-guide/images.md @@ -39,7 +39,7 @@ Maintain a clear and consistent directory structure: Use the following markdown syntax to insert images: -* Image with Caption +### Image with Caption ```markdown ![Caption](../images/sample.png) From 9dd7ee3be64b1eb6e4047abb81b78c0e8224e424 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 3 Feb 2025 09:26:56 +0100 Subject: [PATCH 7/8] Update contributing/documentation/style-guide/images.md Co-authored-by: sofietoft --- contributing/documentation/style-guide/images.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/documentation/style-guide/images.md b/contributing/documentation/style-guide/images.md index da2bf128a6b..c333a06a7ff 100644 --- a/contributing/documentation/style-guide/images.md +++ b/contributing/documentation/style-guide/images.md @@ -63,6 +63,6 @@ Always provide alt text or a caption to describe the image’s purpose and conte ## Best Practices -* Use clear and relevant filenames. For example: dashboard-view.png instead of image1.png. +* 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. From b8c6c8b27e3b9d442289059e4481680230e61161 Mon Sep 17 00:00:00 2001 From: Esha Noronha Date: Mon, 3 Feb 2025 10:21:50 +0100 Subject: [PATCH 8/8] Incorporate comment --- contributing/documentation/style-guide/images.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/contributing/documentation/style-guide/images.md b/contributing/documentation/style-guide/images.md index c333a06a7ff..328b320e258 100644 --- a/contributing/documentation/style-guide/images.md +++ b/contributing/documentation/style-guide/images.md @@ -41,22 +41,30 @@ Use the following markdown syntax to insert images: ### Image with Caption -```markdown +```md ![Caption](../images/sample.png) ``` -* Image with Alt Text (Markdown/GitHub): +### Image with Alt Text (Markdown/GitHub) -```markdown +```md ![Alt text describing the image](images/img.png) ``` -* Image with Alt Text (GitBook) +### Image with Alt Text + +Images added through the GitBook platform are automatically inserted using HTML syntax, as shown in the example below: ```html
The New Backoffice
``` +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 %}