From b28322704661ba4ad5ff22e9b9d78c3be16041c2 Mon Sep 17 00:00:00 2001
From: Xin <xin@imfing.com>
Date: Sat, 23 Sep 2023 23:54:17 +0100
Subject: [PATCH] feat: enhance image resolving (#82)

* feat: enhance image resolving

* chore: don't process image path that begins with relative link

* docs: add instruction for adding images

* chore: update docs

* chore: add filenames to images docs
---
 .../content/docs/guide/organize-files.md      | 60 +++++++++++++++++++
 layouts/_default/_markup/render-image.html    | 27 +++++++--
 2 files changed, 83 insertions(+), 4 deletions(-)

diff --git a/exampleSite/content/docs/guide/organize-files.md b/exampleSite/content/docs/guide/organize-files.md
index 88a73bc3..ec4793b0 100644
--- a/exampleSite/content/docs/guide/organize-files.md
+++ b/exampleSite/content/docs/guide/organize-files.md
@@ -63,3 +63,63 @@ weight: 2
 ## Configure Content Directory
 
 If we need to use a different directory for our content, we can do so by setting the [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) parameter in our site configuration file.
+
+## Add Images
+
+To add images, the easiest way is to put the image files in the same directory as the Markdown file.
+For example, add an image file `image.png` alongside the `my-page.md` file:
+
+{{< filetree/container >}}
+  {{< filetree/folder name="content" >}}
+    {{< filetree/folder name="docs" >}}
+        {{< filetree/file name="my-page.md" >}}
+        {{< filetree/file name="image.png" >}}
+    {{< /filetree/folder >}}
+  {{< /filetree/folder >}}
+{{< /filetree/container >}}
+
+Then, we can use the following Markdown syntax to add the image to the content:
+
+```markdown {filename="content/docs/my-page.md"}
+![](image.png)
+```
+
+We can also utilize the [page bundles][page-bundles] feature of Hugo to organize the image files together with the Markdown file. To achieve that, turn the `my-page.md` file into a directory `my-page` and put the content into a file named `index.md`, and put the image files inside the `my-page` directory:
+
+{{< filetree/container >}}
+  {{< filetree/folder name="content" >}}
+    {{< filetree/folder name="docs" >}}
+        {{< filetree/folder name="my-page" >}}
+            {{< filetree/file name="index.md" >}}
+            {{< filetree/file name="image.png" >}}
+        {{< /filetree/folder >}}
+    {{< /filetree/folder >}}
+  {{< /filetree/folder >}}
+{{< /filetree/container >}}
+
+```markdown {filename="content/docs/my-page/index.md"}
+![](image.png)
+```
+
+Alternatively, we can also put the image files in the `static` directory, which will make the images available for all pages:
+
+{{< filetree/container >}}
+  {{< filetree/folder name="static" >}}
+    {{< filetree/folder name="images" >}}
+        {{< filetree/file name="image.png" >}}
+    {{< /filetree/folder >}}
+  {{< /filetree/folder >}}
+  {{< filetree/folder name="content" >}}
+    {{< filetree/folder name="docs" >}}
+        {{< filetree/file name="my-page.md" >}}
+    {{< /filetree/folder >}}
+  {{< /filetree/folder >}}
+{{< /filetree/container >}}
+
+Note that the image path begins with a slash `/` and is relative to the static directory:
+
+```markdown {filename="content/docs/my-page.md"}
+![](/images/image.png)
+```
+
+[page-bundles]: https://gohugo.io/content-management/page-bundles/#leaf-bundles
diff --git a/layouts/_default/_markup/render-image.html b/layouts/_default/_markup/render-image.html
index 953d87b1..e9836a15 100644
--- a/layouts/_default/_markup/render-image.html
+++ b/layouts/_default/_markup/render-image.html
@@ -1,8 +1,27 @@
-{{- if .Title -}}
+{{- $alt := .PlainText | safeHTML -}}
+{{- $lazyLoading := .Page.Site.Params.enableImagelazyLoading | default true -}}
+{{- $dest := .Destination -}}
+
+{{- $isRemote := not (urls.Parse $dest).Scheme -}}
+{{- $isPage := and (eq .Page.Kind "page") (not .Page.BundleType) -}}
+{{- $startsWithSlash := hasPrefix $dest "/" -}}
+{{- $startsWithRelative := hasPrefix $dest "../" -}}
+
+{{- if and $dest $isRemote -}}
+  {{- if $startsWithSlash -}}
+    {{/* Images under static directory */}}
+    {{- $dest = (relURL $dest) -}}
+  {{- else if and $isPage (not $startsWithRelative) -}}
+    {{/* Images that are sibling to the individual page file */}}
+    {{ $dest = (printf "../%s" $dest) }}
+  {{- end -}}
+{{- end -}}
+
+{{- with .Title -}}
   <figure>
-    <img src="{{ .Destination | safeURL }}" title="{{ .Title }}" alt="{{ .PlainText | safeHTML }}" loading="lazy" />
-    <figcaption>{{ .Title }}</figcaption>
+    <img src="{{ $dest | safeURL }}" title="{{ . }}" alt="{{ $alt }}" {{ if $lazyLoading }}loading="lazy"{{ end }} />
+    <figcaption>{{ . }}</figcaption>
   </figure>
 {{- else -}}
-  <img src="{{ .Destination | safeURL }}" alt="{{ .PlainText | safeHTML }}" loading="lazy" />
+  <img src="{{ $dest | safeURL }}" alt="{{ $alt }}" {{ if $lazyLoading }}loading="lazy"{{ end }} />
 {{- end -}}