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/[email protected]/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)
• [x] Multiple themes and customizable UI
• [x] CSS custom properties for custom themes
• [x] 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.