KeyBlogging Comments

Astro · multi-site

Astro integration guide

Standard way to install KeyBlogging Comments on Astro (and similar) sites. Use this page as the source of truth for site agents — so every property gets the same site-wide login behavior.

Admin tutorial Dashboard Agent API Home

1. How auth works (site-wide)

One GFAVIP login covers the whole site (same origin), not each post page.

2. Prerequisites in KeyBlogging dashboard

1. Premium/Team (or super-admin) account on https://my.keyblogging.com
2. Create company + blog with a stable slug (e.g. miksblogdesign)
3. Set blog domain to the public host only: mikesblogdesign.com (no https://)
4. Note blog slug + use post slug = page slug (e.g. coffee, calendar2026)

3. Per-post embed snippet

On every article/page that should show comments:

<!-- data-* lets embed.js re-bind after Astro soft navigation -->
<div
  id="keyblogging-comments"
  data-blog="YOUR-BLOG-SLUG"
  data-post="YOUR-POST-SLUG"
></div>
<script
  src="https://my.keyblogging.com/static/embed.js?blog=YOUR-BLOG-SLUG&post=YOUR-POST-SLUG&v=6"
  async
></script>

<div id="keyblogging-comments" data-blog="miksblogdesign" data-post="coffee"></div>
<script
  src="https://my.keyblogging.com/static/embed.js?blog=miksblogdesign&post=coffee&v=6"
  async
></script>

Suggested Astro helper

// src/utils/keyblogging.ts
export const KEYBLOGGING_APP = "https://my.keyblogging.com";
export const KEYBLOGGING_BLOG_SLUG = "your-blog-slug";
/** Bump when KeyBlogging ships embed.js updates */
export const KEYBLOGGING_EMBED_VERSION = "6";

export function keybloggingEmbedSrc(postSlug: string) {
  const q = new URLSearchParams({
    blog: KEYBLOGGING_BLOG_SLUG,
    post: postSlug,
    v: KEYBLOGGING_EMBED_VERSION,
  });
  return `${KEYBLOGGING_APP}/static/embed.js?${q}`;
}

4. Cache-bust version constant

Browsers cache embed.js aggressively. Always pass &v=…. When KeyBlogging releases embed fixes, bump KEYBLOGGING_EMBED_VERSION on every Astro site (or set it from an env var shared across repos).

Current recommended value: 6

5. Site-wide auth bridge (required)

Load once in the root layout (every page — not only posts with comments). This catches postMessage from the login popup and writes site-wide storage.

Component sketch: KeybloggingAuthBridge.astro

---
// Include in BaseLayout / every layout that wraps pages
const APP = "https://my.keyblogging.com";
---
<script is:inline define:vars=>
(function () {
  var TOKEN = "keyblogging_embed_token";
  var USER = "keyblogging_embed_user";
  var DAYS = 180;

  function cookieSet(name, val) {
    if (!val) {
      document.cookie = name + "=; Path=/; Max-Age=0; SameSite=Lax";
      return;
    }
    document.cookie =
      name + "=" + encodeURIComponent(val) +
      "; Path=/; Max-Age=" + (DAYS * 86400) + "; SameSite=Lax";
  }

  function persist(token, username) {
    try {
      if (token) {
        localStorage.setItem(TOKEN, token);
        sessionStorage.setItem(TOKEN, token);
        cookieSet(TOKEN, token);
        if (username) {
          localStorage.setItem(USER, username);
          sessionStorage.setItem(USER, username);
          cookieSet(USER, username);
        }
      } else {
        localStorage.removeItem(TOKEN);
        sessionStorage.removeItem(TOKEN);
        localStorage.removeItem(USER);
        sessionStorage.removeItem(USER);
        cookieSet(TOKEN, null);
        cookieSet(USER, null);
      }
    } catch (e) {}
    try {
      var bc = new BroadcastChannel("keyblogging-auth");
      bc.postMessage({ type: "keyblogging-auth", token: token || null, username: username || null });
      bc.close();
    } catch (e) {}
  }

  function accept(data, origin) {
    if (!data || data.type !== "keyblogging-auth" || !data.token) return;
    try {
      if (origin && new URL(origin).hostname !== new URL(APP).hostname) return;
    } catch (e) { return; }
    persist(data.token, data.username || null);
  }

  window.addEventListener("message", function (ev) {
    accept(ev.data, ev.origin);
  });
})();
</script>

6. Canonical host (required)

Redirect www + http → one HTTPS apex (or one www — pick one).

Netlify netlify.toml example

[[redirects]]
  from = "http://www.example.com/*"
  to = "https://example.com/:splat"
  status = 301
  force = true

[[redirects]]
  from = "https://www.example.com/*"
  to = "https://example.com/:splat"
  status = 301
  force = true

[[redirects]]
  from = "http://example.com/*"
  to = "https://example.com/:splat"
  status = 301
  force = true

7. Astro view transitions / soft nav

• Put data-blog and data-post on #keyblogging-comments
• embed.js listens for astro:page-load and re-hydrates auth + reloads the thread
• Still load the auth bridge in the persistent layout shell

8. Optional theme CSS

#keyblogging-comments {
  --kb-fg: inherit;
  --kb-muted: #6b7280;
  --kb-border: #e5e7eb;
  --kb-bg: transparent;
  --kb-accent: #111;
  --kb-radius: 8px;
  --kb-font: inherit;
}

Site-specific look = Astro/site CSS. Embed behavior & defaults = KeyBlogging.

9. Agent checklist & test plan

10. Troubleshooting

Integrate KeyBlogging Comments per https://my.keyblogging.com/docs/astro
- Blog slug: <SLUG>
- Domain: <apex host>
- Embed version: 6
- Include KeybloggingAuthBridge in layouts
- Canonical www/http → https://apex
- data-blog / data-post on comments div
- Cache-bust embed.js with v=6