Usage & Integration

Integrating Diskus into your website is incredibly straightforward. It works beautifully with static site generators (like Astro, Hugo, or Jekyll), Single Page Applications (React, Vue), and traditional CMS platforms (WordPress, Ghost).

1. Register Your Website

Before you can embed the widget, you must register the target domain in your Diskus Backend to authorize it.

1. Log in to your deployed Diskus Dashboard.
2. Navigate to the Websites tab on the sidebar.
3. Click Add New Website and enter your domain name (e.g., myblog.com).
4. Upon creation, the system will provide you with a unique App ID. Save this ID, as you will need it in the next step.

2. Embed the Widget

To display the comment section on your website, paste the following HTML snippet into your target page (usually at the bottom of a blog post layout).

<!-- Diskus Comment Widget Embed -->
<div id="diskus-thread" 
     data-app-id="YOUR_APP_ID" 
     data-thread-key="your-unique-page-slug"
     data-api-url="https://api.your-diskus-domain.com/api/v1">
</div>

<!-- Load the embed script -->
<script src="https://dash.your-diskus-domain.com/widget/dist/embed.js" async defer></script>

Understanding the Data Attributes

Alternative Selector: If you cannot use the #diskus-thread ID, you can use any <div> by attaching the data-diskus-embed attribute to it instead.

Interactive Widget Features

The embedded Diskus widget provides a rich, modern user experience out of the box:

• Markdown Support: Users can write comments using rich text (bold, italic, lists, quotes, inline code, and code blocks). All markdown is securely parsed and sanitized server-side.
• Threaded Replies: Conversations are easy to follow with deep threaded replies supporting up to 3 levels of indentation.
• Likes & Reactions: Users can express agreement by “liking” comments.
• Comment Pinning: Administrators can pin important comments to the top of the thread. Pinned comments receive a special blue star badge.
• Dark Mode Sync: The widget automatically detects the host website’s theme via CSS classes (dark), data-theme attributes, or system prefers-color-scheme, instantly synchronizing its appearance.
• Avatars & Badges: Automatically generates privacy-preserving DiceBear avatars based on email hashes. Administrators receive a prominent green “Author” badge on their comments.

Dynamic Integration (React / Next.js / Astro)

When building Single Page Applications (SPAs) where the page content changes without a full browser reload, the widget needs to be re-initialized.

Diskus automatically monkey-patches history.pushState and listens to popstate, as well as framework-specific events like astro:page-load. However, if you need to manually trigger a re-render, you can call the global API:

// Re-scans the DOM for the widget container and re-initializes
window.DiskusWidget.init();

Here is an example of a reusable component for Astro:

---
// DiskusComments.astro
interface Props {
  threadKey: string;
  title?: string;
}

const { threadKey, title } = Astro.props;
---

<div 
  id="diskus-thread" 
  data-app-id="YOUR_PUBLIC_API_KEY"
  data-thread-key={threadKey}
  data-title={title}
  data-api-url="https://api.yourdomain.com/api/v1"
></div>

<script src="https://api.yourdomain.com/widget/embed.js" defer></script>

How the Shadow DOM Works

Unlike older comment systems that use heavy <iframe> elements or fragile CSS scoping, Diskus injects a native Web Component into your page.

1. The embed.js script finds your <div id="diskus-thread">.
2. It attaches a ShadowRoot to the container in open mode.
3. It mounts a highly-optimized Preact application inside the shadow root, injecting its own Tailwind CSS v4 styles.

The Result: CSS styles from your website cannot accidentally overwrite the widget’s buttons or typography, and the widget’s internal Tailwind classes will never bleed out and ruin your website’s layout. It is 100% collision-proof.