jekyll-opengraph-image 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE.txt +21 -0
  3. data/README.md +91 -0
  4. data/lib/jekyll/opengraph_image_generator.rb +45 -0
  5. data/lib/jekyll-opengraph-image/version.rb +7 -0
  6. data/lib/jekyll-opengraph-image.rb +4 -0
  7. metadata +89 -0
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 3345aba33fa2a149aa11fb755132bbc1066e9b87ec9e04a0d8d68539d8b01059
4
+ data.tar.gz: f2683033e562cb5b1866f8ed365232fc96213d34095fe503370217e2e22d33ac
5
+ SHA512:
6
+ metadata.gz: 4037b4aad00be9d1d51fbe6b79924c68ab037fc2f1cfc9e5b3947c9207bb0163301b344bf109bfcb66eed011cfeada5eb3a7548e2e4aca5c642d9d7856965c73
7
+ data.tar.gz: 3901f9afc20df91556c5c2b7e4e5eaf932280a74f7bc1a07952a7cbe3d06745d6eb2d51348692e9eca754fc5a0224f99235f899266e10cd1f23c67951ff43e9e
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Jason Chance
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,91 @@
1
+ # jekyll-opengraph-image
2
+
3
+ A Jekyll generator plugin that automatically builds `og:image` meta tag URLs from
4
+ a post or page's `image:` frontmatter field — no theme-specific code required.
5
+
6
+ ## Installation
7
+
8
+ Add to your site's `Gemfile`:
9
+
10
+ ```ruby
11
+ gem "jekyll-opengraph-image"
12
+ ```
13
+
14
+ Then add to `_config.yml`:
15
+
16
+ ```yaml
17
+ plugins:
18
+ - jekyll-opengraph-image
19
+ ```
20
+
21
+ Run `bundle install`.
22
+
23
+ ## Usage
24
+
25
+ ### In your `<head>` template
26
+
27
+ ```html
28
+ {% if page.og_image %}
29
+ <meta property="og:image" content="{{ page.og_image }}" />
30
+ {% endif %}
31
+ ```
32
+
33
+ ### In your frontmatter
34
+
35
+ ```yaml
36
+ ---
37
+ title: My Post
38
+ image: /images/my-post-hero.jpg
39
+ ---
40
+ ```
41
+
42
+ The plugin reads `image:`, combines it with your `site.url` and `site.baseurl`,
43
+ and injects the result as `page.og_image`.
44
+
45
+ **If `image:` is already an absolute URL** (starts with `http://` or `https://`),
46
+ it is used as-is — useful for CDN-hosted assets.
47
+
48
+ ## Configuration
49
+
50
+ ### Fallback default image
51
+
52
+ Set a site-wide default `og:image` for posts/pages that have no `image:` frontmatter:
53
+
54
+ ```yaml
55
+ opengraph_image:
56
+ default: /images/default-og.jpg
57
+ ```
58
+
59
+ If a page has no `image:` and no default is configured, `page.og_image` is `nil`
60
+ and the `{% if page.og_image %}` guard in your template suppresses the tag cleanly.
61
+
62
+ ## How it works
63
+
64
+ The generator runs at `priority :low` after all other generators. For each post
65
+ and page it:
66
+
67
+ 1. Reads `page.image` from frontmatter.
68
+ 2. Falls back to `site.opengraph_image.default` if `page.image` is absent.
69
+ 3. Skips the document if neither is present.
70
+ 4. If the resolved value is already an absolute URL, uses it unchanged.
71
+ 5. Otherwise constructs: `site.url + site.baseurl + /image/path`.
72
+ 6. Writes the result to `page.og_image`.
73
+
74
+ ## Edge cases handled
75
+
76
+ | Scenario | Behaviour |
77
+ |---|---|
78
+ | `image` is a relative path | Prepended with `site.url + site.baseurl` |
79
+ | `image` starts with `https://` | Used as-is |
80
+ | `baseurl` is `nil` or empty | Treated as empty string |
81
+ | `image` has leading/trailing whitespace | Stripped |
82
+ | No `image` + no default | `og_image` not set; template guard suppresses the tag |
83
+
84
+ ## Requirements
85
+
86
+ - Jekyll >= 4.0
87
+ - Ruby >= 2.7
88
+
89
+ ## License
90
+
91
+ MIT © Jason Chance 2025
data/lib/jekyll/opengraph_image_generator.rb ADDED
@@ -0,0 +1,45 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "uri"
4
+ require "jekyll"
5
+
6
+ module Jekyll
7
+ class OpengraphImageGenerator < Generator
8
+ priority :low
9
+
10
+ def generate(site)
11
+ default_image = site.config.dig("opengraph_image", "default")
12
+ base_url = build_base_url(site)
13
+
14
+ (site.posts.docs + site.pages).each do |doc|
15
+ image = resolve_image(doc, default_image)
16
+ next if image.nil? || image.strip.empty?
17
+
18
+ doc.data["og_image"] = build_og_image(image.strip, base_url)
19
+ end
20
+ end
21
+
22
+ private
23
+
24
+ def resolve_image(doc, default_image)
25
+ image = doc.data["image"]
26
+ return image if image && !image.to_s.strip.empty?
27
+
28
+ default_image
29
+ end
30
+
31
+ def build_base_url(site)
32
+ url = site.config["url"].to_s.chomp("/")
33
+ baseurl = site.config["baseurl"].to_s.chomp("/")
34
+ "#{url}#{baseurl}"
35
+ end
36
+
37
+ def build_og_image(image, base_url)
38
+ return image if image.start_with?("http://", "https://")
39
+
40
+ # Ensure single slash between base and path
41
+ path = image.start_with?("/") ? image : "/#{image}"
42
+ "#{base_url}#{path}"
43
+ end
44
+ end
45
+ end
data/lib/jekyll-opengraph-image/version.rb ADDED
@@ -0,0 +1,7 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Jekyll
4
+ module OpengraphImage
5
+ VERSION = "0.1.0"
6
+ end
7
+ end
data/lib/jekyll-opengraph-image.rb ADDED
@@ -0,0 +1,4 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "jekyll-opengraph-image/version"
4
+ require "jekyll/opengraph_image_generator"
metadata ADDED
@@ -0,0 +1,89 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: jekyll-opengraph-image
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0
5
+ platform: ruby
6
+ authors:
7
+ - Jason Chance
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 2026-08-21 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: jekyll
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - ">="
17
+ - !ruby/object:Gem::Version
18
+ version: '4.0'
19
+ type: :runtime
20
+ prerelease: false
21
+ version_requirements: !ruby/object:Gem::Requirement
22
+ requirements:
23
+ - - ">="
24
+ - !ruby/object:Gem::Version
25
+ version: '4.0'
26
+ - !ruby/object:Gem::Dependency
27
+ name: minitest
28
+ requirement: !ruby/object:Gem::Requirement
29
+ requirements:
30
+ - - "~>"
31
+ - !ruby/object:Gem::Version
32
+ version: '5.0'
33
+ type: :development
34
+ prerelease: false
35
+ version_requirements: !ruby/object:Gem::Requirement
36
+ requirements:
37
+ - - "~>"
38
+ - !ruby/object:Gem::Version
39
+ version: '5.0'
40
+ - !ruby/object:Gem::Dependency
41
+ name: bundler
42
+ requirement: !ruby/object:Gem::Requirement
43
+ requirements:
44
+ - - "~>"
45
+ - !ruby/object:Gem::Version
46
+ version: '2.0'
47
+ type: :development
48
+ prerelease: false
49
+ version_requirements: !ruby/object:Gem::Requirement
50
+ requirements:
51
+ - - "~>"
52
+ - !ruby/object:Gem::Version
53
+ version: '2.0'
54
+ description: 'A Jekyll generator plugin that reads the image: frontmatter field on
55
+ posts and pages, builds an absolute URL, and injects it as og_image for use in your
56
+ <head> template.'
57
+ email:
58
+ - jason@jasonchance.com
59
+ executables: []
60
+ extensions: []
61
+ extra_rdoc_files: []
62
+ files:
63
+ - LICENSE.txt
64
+ - README.md
65
+ - lib/jekyll-opengraph-image.rb
66
+ - lib/jekyll-opengraph-image/version.rb
67
+ - lib/jekyll/opengraph_image_generator.rb
68
+ homepage: https://github.com/jchance/jekyll-opengraph-image
69
+ licenses:
70
+ - MIT
71
+ metadata: {}
72
+ rdoc_options: []
73
+ require_paths:
74
+ - lib
75
+ required_ruby_version: !ruby/object:Gem::Requirement
76
+ requirements:
77
+ - - ">="
78
+ - !ruby/object:Gem::Version
79
+ version: '2.7'
80
+ required_rubygems_version: !ruby/object:Gem::Requirement
81
+ requirements:
82
+ - - ">="
83
+ - !ruby/object:Gem::Version
84
+ version: '0'
85
+ requirements: []
86
+ rubygems_version: 3.6.2
87
+ specification_version: 4
88
+ summary: Auto-generate og:image meta tag URLs from Jekyll post frontmatter.
89
+ test_files: []