beblob

BeBlob

A lightweight, open-source comment widget that adds GitLab-backed discussions to any website. No backend or database required.

Live Demo | npm | GitLab

Quick Start

1. Create a GitLab OAuth app — Go to GitLab > Settings > Applications. Set the redirect URI to your site URL, enable api and read_user scopes, and ensure "Confidential" is unchecked. Copy the Application ID.

2. Add the script and container to your page:

<script
  id="beblob-script"
  src="https://unpkg.com/beblob@1.6.0/dist/beblob.js"
  data-client-id="YOUR_GITLAB_APPLICATION_ID"
  data-redirect-uri="https://your-site.com/"
  data-project-name="your-gitlab-project"
  data-issue-mapping-strategy="pageTitle"
  data-dev-mode="false"
  data-beblob-version="1.6.0"
  data-theme="light"
></script>

<div id="beblob_thread"></div>

3. Done! Visitors can authenticate with GitLab and leave comments stored as GitLab issues.

How It Works

BeBlob uses GitLab OAuth (Authorization Code flow) to authenticate users. Comments are stored as notes on GitLab issues, with each page mapped to an issue. This means you get GitLab's built-in moderation, notifications, and markdown support for free.

Features

• Markdown comments with live preview and syntax highlighting
• Emoji reactions (thumbsup, thumbsdown, heart, tada, confused)
• Four built-in themes — dark, white, light (default), classic — matching Hexo Cactus themes
• Custom themes via CSS variables — override any color without touching source code
• Mobile responsive — touch-friendly buttons, flexible layouts
• XSS protection — all user content sanitized with DOMPurify
• GitLab OAuth — secure authentication with proper token management
• Zero backend — everything runs client-side with GitLab as the data store

Configuration Options

Option	Required	Description
clientId	Yes	GitLab OAuth Application ID
redirectUri	Yes	Your site URL (must match GitLab app setting)
projectName	Yes	GitLab project name for storing issues
issueMappingStrategy	Yes	How pages map to issues: url, pageTitle, or issueId
issueId	Only with issueId strategy	Specific issue ID to use
devMode	No	"true" loads assets locally; "false" (default) uses CDN
beblobVersion	No	Version for CDN URLs (e.g., "1.6.0")
theme	No	Built-in theme: dark, white, light (default), classic
gitlabUrl	No	GitLab instance URL (default: https://gitlab.com). Use for self-managed GitLab.

Themes

Built-in Themes

Set via data-theme attribute: dark, white, light, classic. These are designed to match Hexo Cactus theme color schemes.

Custom Themes

BeBlob uses CSS custom properties, so you can create your own theme by overriding variables:

.beblob-widget {
  --beblob-bg: #1a1a2e;
  --beblob-text: #e0e0e0;
  --beblob-accent: #e94560;
  --beblob-border: #e94560;
  --beblob-link: #ff6b81;
  --beblob-comment-bg: #16213e;
  --beblob-comment-border: #e94560;
  --beblob-button-bg: #16213e;
  --beblob-button-text: #e0e0e0;
  --beblob-button-border: #e94560;
  --beblob-button-hover-bg: #e94560;
  --beblob-tab-active-bg: #e94560;
  --beblob-tab-active-text: #fff;
  --beblob-editor-bg: #16213e;
  --beblob-editor-border: #e94560;
  --beblob-editor-text: #e0e0e0;
}

Available CSS variables:

Variable	Purpose
--beblob-bg	Widget background
--beblob-text	Primary text color
--beblob-accent	Accent/highlight color
--beblob-border	Default border color
--beblob-link	Link color
--beblob-comment-bg	Comment card background
--beblob-comment-border	Comment card border
--beblob-button-bg	Button background
--beblob-button-text	Button text
--beblob-button-border	Button border
--beblob-button-hover-bg	Button hover background
--beblob-tab-active-bg	Active tab background
--beblob-tab-active-text	Active tab text
--beblob-reaction-bg	Reaction button background
--beblob-popup-bg	Reaction popup background
--beblob-editor-bg	Markdown editor background
--beblob-editor-border	Editor border
--beblob-editor-text	Editor text
--beblob-font-family	Font stack
--beblob-radius	Border radius

Mobile Support

BeBlob is mobile-friendly out of the box:

• Touch-friendly button sizes (44px minimum tap targets)
• Responsive comment layout that stacks on narrow screens
• Full-width action buttons on mobile
• Horizontal-scrolling editor toolbar

Ensure your page includes the viewport meta tag:

<meta name="viewport" content="width=device-width, initial-scale=1">

Hexo / Cactus Integration

Add to your _config.yml:

beblob:
  enabled: true
  client_id: "<your-gitlab-application-id>"
  redirect_uri: "https://yourwebsite.com"
  project_name: "<your-gitlab-project-name>"
  issue_mapping_strategy: "pageTitle"
  version: "1.6.0"
  theme: "light"

Example comments.ejs:

<% if (page.comments && config.beblob.enabled) { %>
  <div class="blog-post-comments">
    <div id="beblob_thread">
      <noscript>Please enable JavaScript to view comments.</noscript>
    </div>
    <% if (config.beblob.dev_mode) { %>
      <script id="beblob-script" src="/js/beblob.js"
              data-client-id="<%= config.beblob.client_id %>"
              data-redirect-uri="<%= config.beblob.redirect_uri %>"
              data-project-name="<%= config.beblob.project_name %>"
              data-issue-mapping-strategy="<%= config.beblob.issue_mapping_strategy %>"
              data-dev-mode="true"
              data-beblob-version="<%= config.beblob.version %>"
              data-theme="<%= config.beblob.theme %>"
              defer>
      </script>
    <% } else { %>
      <script id="beblob-script" src="https://unpkg.com/beblob@<%= config.beblob.version %>/dist/beblob.js"
              data-client-id="<%= config.beblob.client_id %>"
              data-redirect-uri="<%= config.beblob.redirect_uri %>"
              data-project-name="<%= config.beblob.project_name %>"
              data-issue-mapping-strategy="<%= config.beblob.issue_mapping_strategy %>"
              data-dev-mode="false"
              data-beblob-version="<%= config.beblob.version %>"
              data-theme="<%= config.beblob.theme %>"
              defer>
      </script>
    <% } %>
  </div>
<% } %>

For a working example, see antonbelev.gitlab.io.

Sites Using BeBlob

• belev.me

Inspiration

BeBlob was inspired by giscus and utterances — similar tools for GitHub. This project brings the same experience to GitLab.

Roadmap

• Comment management (edit, delete, moderate)
• Configurable reactions (opt-in/out)
• Multiple themes and customizable UI
• CSS custom properties for custom themes
• Mobile responsive design
• Hexo plugin for direct integration
• Threaded/nested replies

Support

Found a bug or have a feature request? Open an issue.

License

MIT — see LICENSE for details.