docs(examples): add image reference example note with all three scenarios

Adds notes/example-images.org demonstrating how org-mode image links of
each kind pass through ox-hugo and land in content/:

  Scenario 1 — External URL: linked image using #+ATTR_HTML + a local
    thumbnail as the display image; ox-hugo emits a {{< figure >}} shortcode
    with a link= attribute pointing to the remote URL.

  Scenario 2 — Local file (same notes dir): [[file:quartz-logo.jpg]]
    ox-hugo copies the file to static/ox-hugo/ and rewrites the src to
    /ox-hugo/quartz-logo.jpg.

  Scenario 3 — Absolute path outside notes dir: [[file:/abs/path/img.jpg]]
    ox-hugo copies the file from outside the notes tree into static/ox-hugo/
    and rewrites the src identically to scenario 2.

Also adds:
  notes/quartz-logo.jpg          — image asset for scenarios 1 & 2
  notes-external/                — simulates an assets dir outside notes
  static/ox-hugo/ added to .gitignore (populated at export time)
This commit is contained in:
Ignacio Ballesteros
2026-02-20 10:09:54 +01:00
parent 9ecc9336da
commit a907d6513b
4 changed files with 35 additions and 0 deletions

33
notes/example-images.org Normal file
View File

@@ -0,0 +1,33 @@
:PROPERTIES:
:ID: example-images
:END:
#+title: Example: Image References
This note demonstrates the three image reference scenarios that the pipeline
must handle.
* Scenario 1: External image (URL)
An image hosted on the web — ox-hugo passes the URL through as-is and no
local file handling is needed.
#+ATTR_HTML: :alt Quartz logo (external URL)
[[https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSkzsTuLOt8esM6enoKwkzqA52G3p9hldlf2g&s][file:quartz-logo.jpg]]
* Scenario 2: Local image (same notes directory)
An image sitting next to this .org file inside the notes directory.
ox-hugo copies files referenced with a relative path into the Hugo =static/=
assets tree automatically.
#+CAPTION: Quartz logo (local, same notes dir)
[[file:quartz-logo.jpg]]
* Scenario 3: External image (outside notes directory)
An image that lives outside the notes directory entirely — for example a
shared assets folder or a system path. ox-hugo still copies it into =static/=
and rewrites the reference.
#+CAPTION: Quartz logo (outside notes dir)
[[file:/home/ignaciobll/code/quartz-org-roam/notes-external/external-location-image.jpg]]