https://github.com/matt-goldman/blakeplugin.opengraph
A Blake plugin that generates OpenGraph meta tags for generated pages
https://github.com/matt-goldman/blakeplugin.opengraph
blake blazor open-graph ssg static-site-generator
Last synced: 5 months ago
JSON representation
A Blake plugin that generates OpenGraph meta tags for generated pages
- Host: GitHub
- URL: https://github.com/matt-goldman/blakeplugin.opengraph
- Owner: matt-goldman
- License: mit
- Created: 2025-08-19T19:38:04.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-03T19:44:32.000Z (9 months ago)
- Last Synced: 2025-09-28T05:26:49.537Z (9 months ago)
- Topics: blake, blazor, open-graph, ssg, static-site-generator
- Language: C#
- Homepage:
- Size: 151 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Blake OpenGraph Plugin (per‑route shells for social previews)
Add correct Open Graph tags to every Blake‑generated page without SSR, prerender, or edge functions. The plugin emits a small, standalone HTML "shell" per page at `/.../index.html` so social scrapers (which don’t run JS) get the right `` on first byte.
**Scope:** _only_ pages Blake generates from markdown. The site’s home page (`wwwroot/index.html`) is **not** modified.
## What does it do
Blazor WASM (and most SPAs) inject `` after the app boots. Social bots (Facebook, X/Twitter, LinkedIn, Slack, Discord, etc.) don’t execute JS, so they miss your OG tags. This plugin solves that by baking a per‑route HTML shell containing the correct meta, while retaining the Blazor UX.
* Reads existing shell from `wwwroot/index.html`.
* Builds a compact SEO/social `` block per content page (title, description, canonical, `og:*`).
* Writes a per‑page shell to `wwwroot//index.html`.
* Leaves your home page and the rest of your app untouched.
**Result:**
* Bots fetch `/posts/my-post/` and receive a real HTML file with the correct `` immediately.
* Humans (browsers) fetch the same URL and your Blazor app boots as normal.
## Installation
1. **Add the plugin** to your Blake site
```bash
dotnet add package BlakePlugin.OpenGraph
```
2. **Bake** with the required options (see Configuration). Example:
```bash
blake bake --social:baseurl="https://example.com"
```
**Note:** You can omit the base URL argument in debug, but the plugin will not be able to generate absolute URLs for your Open Graph tags so you should include this in any CI builds.
The plugin writes files directly into your project’s `wwwroot/` so they’ll be included by `dotnet build` and whatever static host you use.
### Optimisation
You don't need the output generated by this in your repo, and you usually don't need it when debugging. To optimise for this, I recommend adding a release condition to the package import:
```xml
```
## Configuration
**Required (Production):**
* `--social:baseurl`: Full origin used to build **absolute** URLs for `og:url`, `og:image`, and `canonical`.
* Examples: `https://example.com`, `https://user.github.io/repo`
## Output
For each generated page, the plugin writes:
```
wwwroot/
posts/
post-title/
index.html <-- shell with correct (OG/Twitter/canonical)
```
The shell links to your existing CSS/JS; only the `` differs per page.
> The home page (`wwwroot/index.html`) is not altered by this plugin.
---
## Meta set the plugin emits
The plugin uses [Blake standard frontmatter](https://blake-ssg.org/2%20using%20blake/authoringcontent#frontmatter) so there is no additional configuration required.
```yaml
# example.md
---
title: "Post title"
description: "Short summary for cards"
image: "/images/og/post-title.png" # optional; plugin makes absolute via baseurl
tags: ["example", "post"]
...etc.
---
```
The plugin emits the following meta tags for each generated page:
* `` - mapped from the `title` in frontmatter
* `` - mapped from the `description` in frontmatter
* `` - built from the page URL combined with the `baseurl`
* `` (content pages)
* `` - mapped from the `title` in frontmatter
* `` - mapped from the `description` in frontmatter
* `` - built from the page URL combined with the `baseurl`
* `` - built from the `image` in frontmatter (if present, omitted if not)
Values are HTML‑escaped; URLs are normalized and made absolute using `baseurl`.
## Validation checklist
* **Curl:**
```bash
curl -s https://example.com/posts/post-title/ | grep -i "og:"
```
* **Debuggers:** use Facebook Sharing Debugger, X Card Validator, and LinkedIn Post Inspector to refresh caches and verify cards.
* **Image:** ensure your OG image returns 200, has proper `Content-Type`, is ≥ 1200×630, and < \~5 MB.
---
## Troubleshooting
* **Missing per‑route file:** confirm the page’s `slug` and that the plugin ran during `blake bake`.
* **Wrong URLs (nested paths):** set `--social:baseurl` or use rooted links in your app.
* **Double slashes:** the plugin normalizes common `//` patterns; still prefer clean paths in front‑matter.
* **No previews:** some platforms cache aggressively—use their debuggers to “scrape again.”
## Limitations (by design)
* The plugin only emits meta **in the head**. It does not SSR your page body.
* The site home page is not modified (ensure you add your own meta tags there).
* The plugin only handles Open Graph tags (i.e. no Twitter Cards).