https://github.com/paperstrike/hexo-filter-probe-image-size
Probe and set image sizes in Hexo web pages
https://github.com/paperstrike/hexo-filter-probe-image-size
hexo-plugin image-size
Last synced: about 1 month ago
JSON representation
Probe and set image sizes in Hexo web pages
- Host: GitHub
- URL: https://github.com/paperstrike/hexo-filter-probe-image-size
- Owner: PaperStrike
- License: mit
- Created: 2021-06-21T19:12:03.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2023-01-16T05:05:12.000Z (over 2 years ago)
- Last Synced: 2024-04-24T21:22:14.805Z (about 1 year ago)
- Topics: hexo-plugin, image-size
- Language: JavaScript
- Homepage:
- Size: 244 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# hexo-filter-probe-image-size
[](https://www.npmjs.com/package/hexo-filter-probe-image-size)
Probe and set `width` and `height` to `![]()
` elements.
As [modern best practice - Optimize Cumulative Layout Shift | web.dev](https://web.dev/optimize-cls/#modern-best-practice) 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](https://github.com/nodeca/probe-image-size).
---
🐿️ Jump to [Examples](#examples), [Q&A][q-a], or [Contributing Guide][contributing].
## Usage
Available configurations and default values. Configure them in Hexo `_config.yml`.
```yaml
# Probe ![]()
sizes and set related attributes.
probe_image_size:
enable: false
# https://hexo.io/api/filter#Synopsis
priority: 10
# An array containing the rules to resolve an image path.
# If an image matches multiple proxy rules, the resolved
# paths will be probed in order until one gives a size.
proxies:
# By default, we use the local image that has the same
# file name instead of do a real HTTP request to probe.
- name: HTTP to local
# A regex or string used to specify substrings
# that are replaced with the specified target string.
match: ^(https?:)?//.+/
# The string that replaces the substring
# specified by the match above.
target: images/
```
When resolving an image path (usually grabbed from `![]()
`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/`:
```yaml
probe_image_size:
enable: true
proxies:
- name: My CDN
match: ^https://example/img/
target: /home/demo/Pictures/
```
### Proxy specific files
For files with a name prefixed by `Primo-`, use `D:/Primo/pics/`:
```yaml
probe_image_size:
enable: true
proxies:
- name: El Primo
match: ^.+/(?=Primo-[^/]+$)
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:
```yaml
probe_image_size:
enable: true
proxies:
- name: HTTP to local
match: ^(https?:)?//.+/
target: images/
# When proxy above failed to target a parsable image.
- name: All images folder
match: ^.+/
target: /a/path/expected/to/contain/all/images/
# When above failed, too.
- name: Try Original
# Match all, as all paths contain the empty string.
match: ''
target: ''
```
### No proxy
Use the original path directly:
```yaml
probe_image_size:
enable: true
proxies: []
```
### Run later than others
_See [Filter | Hexo](https://hexo.io/api/filter#Synopsis) 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.
```yaml
probe_image_size:
enable: true
priority: 11
```
Or manage the order totally on your own.
```yaml
some_other_filter_that_also_supports_priority:
priority: 11
probe_image_size:
enable: true
priority: 12
```
## [Q&A][q-a]
## [CONTRIBUTING][contributing]
## [LICENSE](LICENSE)
[q-a]: https://github.com/PaperStrike/hexo-filter-probe-image-size/discussions/categories/q-a
[contributing]: https://github.com/PaperStrike/hexo-filter-probe-image-size/blob/main/.github/CONTRIBUTING.md