All jobs

Add Open Graph and Twitter Card Tags to a Jekyll Blog on GitHub Pages

Yes. An agent completes your share tags with the jekyll-seo-tag plugin GitHub Pages already ships, keeps your layout's title, builds the site, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads what the site already emits before it adds a tag, because a blog started from barryclark/jekyll-now has half of them. _includes/meta.html writes the charset and viewport lines, then description and og:description from page.excerpt or site.description, an author meta from site.name, and og:title and twitter:title when the page has a title. What it never writes is og:url, og:type, og:site_name, og:image, twitter:card or a canonical link, so a shared link gets a title and a sentence and no picture, and a crawler gets no canonical. _layouts/default.html builds its own <title> from page.title, site.name and site.description and includes meta.html in the head. _config.yml has name, description, an avatar pointing at images/jekyll-logo.png on raw.githubusercontent.com, footer-links.twitter: jekyllrb, an empty url:, baseurl: "", permalink: /:title/, and jekyll-sitemap and jekyll-feed under the pre-3.5 gems: key; there is no Gemfile, because .gitignore excludes it and the README's workflow is to fork and let GitHub Pages build. That build uses the github-pages gem, today version 233, which pins Jekyll 3.10.0 and bundles jekyll-seo-tag 2.9.1, so the plugin is already available and nothing can be installed anyway.

So the agent uses the plugin rather than hand-writing nine more tags. In _config.yml it renames gems: to plugins: and adds jekyll-seo-tag, adds a title: beside name: because the plugin reads site.title for og:site_name and name is what the theme's header uses, fills url: with the site's address because the plugin writes og:url and the canonical link only when site.url is set, and adds twitter: {username, card} from the existing footer handle and a logo: for the JSON-LD publisher. A front-matter default under defaults: gives every page image: /images/jekyll-logo.png, so a post without its own image: still shares with a picture, and the plugin turns that relative path into an absolute og:image and twitter:image. In _includes/meta.html the agent keeps the charset, viewport and compatibility lines and replaces the description, author and title block with {% seo title=false %}: title=false because default.html already renders a <title> in the house format and the plugin would otherwise add a second one.

What the plugin then writes per page, the agent reads from a build rather than from its documentation: on a post, og:title, og:locale, description with twitter:description and og:description from the excerpt, the canonical link and og:url at the post's /:title/ address, og:site_name, og:image, og:type article with article:published_time from the post date, twitter:card, twitter:image, twitter:title and twitter:site, plus a JSON-LD BlogPosting block with the publisher; on the index, og:type website. The og:description the old include produced from the excerpt is still there, now from the same fallback chain, so nothing a previous share had is lost.

To prove it, the agent installs Ruby and gem install github-pages in its sandbox, which is the README's own instruction, and runs github-pages build under a UTF-8 locale, which that command needs. It reads _site/<post>/index.html and _site/index.html, pastes the head of each into the pull request, and confirms there is exactly one <title> per page. It also checks the one thing a plugin cannot: that url: is the real address, since a wrong value becomes the canonical of every page.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add Open Graph and Twitter Card tags to this Jekyll blog, which GitHub Pages builds. Read _config.yml, .gitignore, README.md, _layouts/default.html, _layouts/post.html, _includes/meta.html, index.html and the files under _posts/ first. Use the jekyll-seo-tag plugin the github-pages gem bundles; add no Gemfile. In _config.yml rename the gems key to plugins and add jekyll-seo-tag, add a title matching name, set url to the site's address, add twitter username and card from the footer handle, a logo, and a front-matter default giving every page image: /images/jekyll-logo.png. In _includes/meta.html keep the charset, viewport and compatibility lines and replace the description, author and title tags with {% seo title=false %}, since default.html renders its own title. In the sandbox install the github-pages gem, run github-pages build with a UTF-8 locale, and open a pull request that pastes the head of the built post page and index page and confirms one title tag per page.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that changes two files: _config.yml (the plugins: key with jekyll-seo-tag, title, url, twitter, logo and the image default) and _includes/meta.html (the {% seo title=false %} line in place of the hand-written tags). The layouts, posts and styles are untouched. The description pastes the built head of the post page and the index page, with the og:, twitter:, canonical and JSON-LD lines visible.

The run's record holds the gem install, the build and the file reads, so a reviewer sees the exact tags GitHub Pages will emit, from the same Jekyll and plugin versions the github-pages gem pins, without building the site themselves.

Before merging, a reviewer confirms url: is the site's real address, decides whether twitter.card should be summary or summary_large_image for the logo they have, and swaps the default image for one made for sharing if the logo is not it. Posts can override with their own image: front matter from then on.

Run it on every Linear issue labelled seo

Create an automation in the Project with a linear trigger on linear.issue.labeled with seo in its labels, and this prompt. The trigger adds the issue after the prompt as untrusted event text, so an issue that names the site address, the handle to credit or the image to share with reaches the agent and goes into _config.yml instead of a placeholder.

Each labelled issue starts one run in its own sandbox and opens one pull request on its own branch. Changes made by an app integration never fire the trigger, and the automation's max_runs_per_hour caps how many start in an hour.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

The tags themselves are a solved problem; the work is knowing which of the site's values the plugin reads and which it does not: site.title rather than name, a url that must be set or there is no canonical, a gems: key Jekyll 3.5 stopped reading, and a layout that already prints a title. Each of those is a silent failure on GitHub Pages, where the only feedback is a share card that still has no image. The agent reads the config and the include first, then builds the site in its own sandbox with the same gem GitHub Pages uses and reads the output, so the pull request shows the tags rather than describing them.

Nothing is installed on the reader's machine, every command and its output stays on the run, and the diff is two files. The same request can run on every Jekyll site a team keeps, each run reading that site's own config and layout.

Frequently asked questions

Why a plugin instead of writing the tags by hand?

Because the plugin is already there: GitHub Pages builds with the github-pages gem, which bundles jekyll-seo-tag 2.9.1, and this repository has no Gemfile to add anything else. Hand-written tags would also need the absolute-URL and escaping logic the plugin already has, and would not produce the JSON-LD block.

Why {% seo title=false %}?

_layouts/default.html already renders <title> as the page title, the site name and the description. Without title=false the plugin writes a second <title>, which browsers and crawlers handle unpredictably. The option keeps the layout's title and emits everything else.

Where does og:image come from?

From a front-matter default in _config.yml that gives every page image: /images/jekyll-logo.png, which the plugin turns into an absolute og:image and twitter:image using url. A post that sets its own image: wins, and image can be an object with height, width and alt when the dimensions are known.

What happens if url: is left empty?

The plugin skips the canonical link and og:url, and relative image paths cannot be made absolute, so most of what this change is for does not appear. That is why the pull request asks the reviewer to confirm the address; on a user site it is https://<username>.github.io, on a project site it also needs baseurl.

Does the plugin change the description the old include produced?

No. The old include used page.excerpt with HTML stripped, falling back to site.description, and the plugin reads page.description, then the excerpt, then the site description, so a post with no front-matter description gets the same text as before, now in description, og:description and twitter:description at once.

More Jekyll jobs

The same job on other stacks

Keep reading