hexo-filter-probe-image-size

Probe and set width and height to <img> elements.

As modern best practice - Optimize Cumulative Layout Shift | web.dev describes, developers should always set the width and height attributes without units in HTML, and set one of them to auto in CSS.

Core: nodeca/probe-image-size.

---

🐿️ Jump to Examples, Q&A, or Contributing Guide.

Usage

Available configurations and default values. Configure them in Hexo _config.yml.

1# Probe <img> sizes and set related attributes.
2probe_image_size:
3
4  enable: false
5
6  # https://hexo.io/api/filter#Synopsis
7  priority: 10
8
9  # An array containing the rules to resolve an image path.
10  # If an image matches multiple proxy rules, the resolved
11  # paths will be probed in order until one gives a size.
12  proxies:
13
14    # By default, we use the local image that has the same
15    # file name instead of do a real HTTP request to probe.
16    - name: HTTP to local
17
18      # A regex or string used to specify substrings
19      # that are replaced with the specified target string.
20      match: ^(https?:)?//.+/
21
22      # The string that replaces the substring
23      # specified by the match above.
24      target: images/

When resolving an image path (usually grabbed from <img>s' src attributes), this filter firstly checks if the path matches ^(https?:)?//. If not, will format it to a relative path that has no query string.

By using proxies, you can resolve these possibly formatted paths back to absolute paths. Proxy-resolved absolute paths represent files from the file system. E.g., /home/foo/Pictures/ does represent /home/foo/Pictures/ on POSIX, and D:/home/foo/Pictures/ on Windows (assume you run Hexo in D:), instead of the one based on the generating folder.

The whole process won't mutate any original src values.

Examples

Proxy specific URL

For files in my own image CDN https://example/img/, use /home/demo/Pictures/:

1probe_image_size:
2  enable: true
3  proxies:
4    - name: My CDN
5      match: ^https://example/img/
6      target: /home/demo/Pictures/

Proxy specific files

For files with a name prefixed by Primo-, use D:/Primo/pics/:

1probe_image_size:
2  enable: true
3  proxies:
4    - name: El Primo
5      match: ^.+/(?=Primo-[^/]+$)
6      target: D:/Primo/pics/

Proxy fallbacks

For files failed to access in previous proxy, use /a/path/expected/to/contain/all/images/, and if failed again, use the original path:

1probe_image_size:
2  enable: true
3  proxies:
4    - name: HTTP to local
5      match: ^(https?:)?//.+/
6      target: images/
7    # When proxy above failed to target a parsable image.
8    - name: All images folder
9      match: ^.+/
10      target: /a/path/expected/to/contain/all/images/
11    # When above failed, too.
12    - name: Try Original
13      # Match all, as all paths contain the empty string.
14      match: ''
15      target: ''

No proxy

Use the original path directly:

1probe_image_size:
2  enable: true
3  proxies: []

Run later than others

See Filter | Hexo for filter priority description.

As most of Hexo filters use a priority of 10, setting it to 9 or 11 makes our probe process runs earlier or later than them.

1probe_image_size:
2  enable: true
3  priority: 11

Or manage the order totally on your own.

1some_other_filter_that_also_supports_priority:
2  priority: 11
3
4probe_image_size:
5  enable: true
6  priority: 12

Q&A

CONTRIBUTING

LICENSE