@gurupanguji

Mastodon Embed Phase 1 Design

Problem

Issue #117 identifies bare Mastodon post URLs in blog posts that should render as Mastodon embeds.

Example shape:

https://mastodon.social/@JuliusGoat/109551955251655267

These currently render as plain links or bare URLs instead of richer embeds.

Goals

1. Convert standalone bare Mastodon post URLs into explicit Mastodon embed markup.
2. Keep Phase 1 narrow and unambiguous.
3. Add validation so new Phase 1 cases do not regress.

Non-Goals

1. Do not convert markdown links to Mastodon posts yet.
2. Do not convert Mastodon links embedded inside surrounding prose.
3. Do not attempt a general-purpose fediverse embed system in this pass.

Phase Split

Phase 1

Only convert standalone bare Mastodon post URLs.

Phase 2

Convert markdown links to Mastodon posts when they appear alone on their own line.

Candidate Approaches

1. Layout-time replacement

Detect Mastodon URLs during rendering and replace them with embed markup in the layout.

Pros:

• Minimal content churn.

Cons:

• Hidden behavior.
• Harder to reason about and validate.
• More brittle with mixed legacy markup.

2. Bulk content normalization

Rewrite matched posts to explicit Mastodon embed markup in source files.

Pros:

• Explicit output.
• Easy to inspect in diffs.
• Stable across builds.

Cons:

• Larger archive diff.

3. Hybrid

Normalize content and add validator coverage for the risky input pattern.

Pros:

• Explicit content plus future guardrails.

Cons:

• Slightly more setup.

Recommendation

Use approach 3.

Phase 1 should normalize only lines that are:

• standalone
• bare
• Mastodon post URLs

into canonical Mastodon embed markup that includes:

• a wrapper block
• the mastodon-embed blockquote markup
• the provider script

The wrapper should be repo-owned so future styling can target Mastodon embeds as a group.

Canonical Output

Phase 1 should produce a wrapper similar to:

<div class="gp-mastodon-embed">
  <blockquote class="mastodon-embed" data-embed-url=".../embed">
    ...
  </blockquote>
  <script data-allowed-prefixes="https://mastodon.social/" async src="https://mastodon.social/embed.js"></script>
</div>

For this pass, it is acceptable to keep the provider-specific inline styles from the issue example if that is the stable embed shape.

Detection Rules

Phase 1 should match only lines where the whole non-whitespace line is a Mastodon post URL such as:

https://mastodon.social/@user/123456789012345678

Do not match:

• markdown links
• URLs inside paragraphs
• URLs inside blockquotes
• URLs already converted to embed markup

Validation

Add validator coverage that flags standalone bare Mastodon post URLs in posts that fall under the enforcement window for this feature.

The validator should not flag:

• existing embed markup
• markdown links on their own line yet
• prose lines containing Mastodon URLs

Verification

1. Identify all Phase 1 candidates in _posts/.
2. Convert them with a script.
3. Add focused tests for:
   • candidate detection
   • markup generation
   • idempotence
   • validator coverage
4. Spot-check the issue example post after conversion.

Acceptance Criteria

1. Standalone bare Mastodon post URLs are converted to explicit embed markup.
2. The issue example post is fixed by Phase 1.
3. Validation flags future Phase 1 regressions.
4. Markdown-link-only Mastodon cases remain untouched for the later Phase 2 pass.