All jobs

Add Open Graph Tags to a Pelican Blog

Yes. An agent adds Open Graph and Twitter card tags to a Pelican theme's base and article templates, with a per-article image, 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 the theme's head before it adds tags to it. In a site laid out like getpelican/pelican-blog, the theme lives in the repository at themes/notmyidea, and base.html has a <head> with the charset, a title block, the stylesheet link and the Atom and RSS <link rel="alternate"> lines, and nothing else: no description, no og: property and no block a child template could fill. article.html extends it and overrides only title and content; page.html and index.html do the same. pelicanconf.py sets SITENAME, AUTHOR, SITEURL = "" for local builds, STATIC_PATHS = ["images", "extra"] with EXTRA_PATH_METADATA that moves the favicon and the touch icons from content/extra to the site root, and publishconf.py sets SITEURL = "https://blog.getpelican.com". content/logo/pelican-logo.png exists but logo is not in STATIC_PATHS, so the build does not copy it.

The agent adds a meta block to base.html with the site-wide tags: og:site_name from SITENAME, og:type of website, og:title from the page title, og:url from SITEURL and the output file, a description and og:description from a new SITE_DESCRIPTION setting, and twitter:card set to summary. article.html overrides the block: og:type becomes article, og:description is article.summary | striptags | truncate(200), the summary Pelican builds from the first SUMMARY_MAX_LENGTH words when a post sets none, article:published_time is article.date.isoformat(), article:modified_time is added when article.modified exists, which namespace-plugins.md sets through its Modified field, and each tag becomes an article:tag. The image is article.og_image when a post sets that field in its metadata, else a site default from an OG_IMAGE setting, and the agent adds logo to STATIC_PATHS so the logo PNG is copied and can be the default, with twitter:card switched to summary_large_image only when an image is present.

Two details come from reading rather than guessing. Every og:url and og:image is built from SITEURL, and pelicanconf.py leaves that empty, so a make html build produces relative values and only make publish produces the absolute ones the validators want; the pull request says so and checks the publish output. And the touch icons in content/extra are 180 pixels at most, which previewers accept but render small, so the default image is the logo rather than an icon, with a sentence recommending a 1200 by 630 image under content/images for the site.

Then the agent builds both ways in its own sandbox, with the current Pelican 4.12.0 and Markdown 3.11.2 installed, running make html and make publish. It reads output/index.html for the site tags and the article page for pelican-4.7-released for the article tags, confirms the article:modified_time on the namespace plugins post and its absence elsewhere, confirms og:url is absolute in the publish build, and serves output to open an article in its own browser and read the tags from the page source. The one .md post and the .rst posts go through the same template, and the build log shows no new warnings.

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 meta tags to this Pelican site's theme. Read pelicanconf.py, publishconf.py, the Makefile, the content directory and every template under the theme's templates directory first. Add a meta block to base.html with og:site_name, og:type, og:title, og:url, description, og:description and twitter:card, and override it in article.html with og:type article, the article summary stripped of HTML as the description, article:published_time, article:modified_time when the article has a modified date, one article:tag per tag, and an image from an og_image metadata field falling back to an OG_IMAGE setting. Add SITE_DESCRIPTION and OG_IMAGE to pelicanconf.py and make sure the default image is copied by the build. Install the current Pelican and Markdown, run make html and make publish, confirm the tags on the index and on an article in the publish output and that og:url is absolute there, open an article in a browser, and open a pull request linking the issue with the commands and their output.",
  "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

The pull request changes themes/notmyidea/templates/base.html, themes/notmyidea/templates/article.html and pelicanconf.py. Its description quotes the make publish output, the <meta> lines from the built index and from one article with absolute URLs, the article:modified_time line from the one post that has a modified date, and a note on the image size. No content file changes, and publishconf.py is untouched.

A reviewer checks the site description text, the default image, and whether the summary or a dedicated description metadata field should feed og:description. After merging, the next make upload serves the tags, and a post that sets og_image in its metadata gets its own preview image.

Run it on every Linear issue labelled seo

An automation in the Project that holds the site takes a linear trigger on linear.issue.labeled with the label seo. Its runs are read-only, so the saved prompt asks for a plan: the run reads the theme's head and the settings and posts which tags it would add, which template each goes in and what the default image would be as a comment on the issue. A handler on the team's own server then starts the run that writes the pull request, sending this body with the issue's URL added to resources and a request_id that is a UUID v5 of the issue id, so a retried start returns the run already started.

A team with several Pelican sites sends one request per repository, each with its own resources entry.

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

Why run it on Rush?

Meta tags are easy to write and easy to get quietly wrong: a relative og:url from the development settings, an image the build never copies, a summary that still carries HTML, a modified time on posts that were never modified. Each is only visible in a built site, so the agent installs Pelican in its own sandbox, builds with both configurations, reads the generated head of the index and an article, opens one in a browser, and keeps every command and its output in the run's record.

It also fits the site as it is: a theme already in the repository, settings in pelicanconf.py the way the existing ones are, and a static path added rather than an image moved. Ten Pelican sites with ten themes get ten pull requests, each putting the block where that theme's base.html builds its head.

Frequently asked questions

Why do the tags have relative URLs when I run make html?

Because pelicanconf.py sets SITEURL to an empty string for local work and every og:url and og:image is prefixed with it. make publish builds with publishconf.py, which sets the real host, and that output is what make upload ships; the pull request checks that build.

Can one post use its own image?

Yes. Add og_image to the post's metadata, as a :og_image: field in reStructuredText or an og_image: line in Markdown, with a path under a static directory. The template uses it before the OG_IMAGE default and switches the Twitter card to the large image layout.

Does this change what the RSS and Atom feeds contain?

No. Feeds are generated from article content and metadata, not from the theme's templates, so the new tags appear only in the HTML head. The feed <link> lines in base.html stay where they are.

Is a plugin a better fit?

The theme is in the repository, so a template edit is the smallest change and works with any Pelican version the site uses. A plugin would add a dependency to a site with no requirements file and still need the theme to render its output; the pull request keeps everything in the two templates and the settings file.

More Pelican jobs

The same job on other stacks

Keep reading