Comment System

Xingluo integrates three comment systems — giscus, twikoo, and waline — selectable via features.comments.

Configuration

Choose a provider and supply its config in features.comments in xingluo.config.ts:

ts
features: {
  comments: {
    provider: "giscus", // "giscus" | "twikoo" | "waline" | false
    giscus: { /* giscus config */ },
    // twikoo: { /* twikoo config */ },
    // waline: { /* waline config */ },
  },
}

With provider: false (default), comments are off and post pages emit no comment markers or scripts.

Comment Section Location

The comment section appears only at the bottom of post detail pages (after the prev/next navigation), rendered by src/components/comments/Comments.astro.

giscus

A comment system based on GitHub Discussions; the repository must be public with Discussions enabled.

Configuration

ts
comments: {
  provider: "giscus",
  giscus: {
    repo: "owner/repo",           // GitHub repository
    repoId: "R_...",              // Repository ID (generated by giscus.app)
    category: "Announcements",    // Discussion category name
    categoryId: "DIC_...",        // Category ID (generated by giscus.app)
    mapping: "pathname",          // optional, page-to-discussion mapping
    strict: false,                // optional, strict title matching
    reactionsEnabled: true,       // optional, reactions
    inputPosition: "bottom",      // optional, comment box position: top | bottom
    loading: "lazy",              // optional, loading: lazy | eager
  },
}

Obtaining repoId / categoryId

1. Visit giscus.app
2. Enter the repository and category to generate the config
3. Copy data-repo-id and data-category-id into your config

How It Works

giscus injects an iframe via the official client.js, with data-* attributes carrying the config. The language auto-maps to the current locale (zh-cn → zh-CN, en → en). The theme is synced on toggle via postMessage.

twikoo

A comment system with no backend dependency, supporting Tencent CloudBase or self-hosting.

Configuration

ts
comments: {
  provider: "twikoo",
  twikoo: {
    envId: "https://your-twikoo.example.com", // Cloud environment ID or full self-host URL
    lang: "zh-CN",                            // optional, language
  },
}

envId Notes

• Tencent CloudBase: fill the environment ID (requires the cloudbase SDK)
• Self-hosted: fill the full URL (e.g. https://twikoo.example.com); twikoo auto-detects HTTP API mode

How It Works

twikoo dynamically import("twikoo") and calls init when the comment container enters the viewport. twikoo does not support runtime theme switching; the site rebuilds it on theme change to apply dark styles.

waline

A backend-backed comment system with comment counts and view counts.

Configuration

ts
comments: {
  provider: "waline",
  waline: {
    serverURL: "https://waline.example.com", // Waline server address
    lang: "zh-CN",                           // optional, language
    pageSize: 10,                            // optional, comment page size
    dark: "html.dark",                       // optional, dark selector (defaults to site .dark)
  },
}

serverURL Deployment

Refer to the Waline docs to deploy the server (Vercel / Cloudflare / self-host all work), then put the address in serverURL.

How It Works

waline dynamically import("@waline/client") and the style @waline/client/style when the comment container enters the viewport, then calls init. The dark:"html.dark" selector auto-follows the site dark mode; no manual sync needed.

Lazy Loading

All comment systems are lazy-loaded via IntersectionObserver: requests and initialization happen only when the comment container is within 200px of the viewport, avoiding first-paint performance cost.

See src/scripts/comments.ts.

Theme Sync

When the site theme changes, the comment system theme syncs automatically:

Theme watching uses a MutationObserver on document.documentElement’s class and data-theme attributes.

View Transitions Adaptation

The comment script listens for astro:page-load and re-scans mount points after each page load. Re-initialization is prevented via dataset markers (xng-setup, xng-init).

i18n

The comment section title is localized via UIStrings.comments.title (“Comments” in both zh-cn.ts and en.ts). The comment system UI language is controlled by each provider’s lang field.

Custom Extensions

Switching Providers

Change features.comments.provider in xingluo.config.ts; no code changes needed. Xingluo renders the corresponding sub-component automatically.

Adding a Comment System

1. Create a new component under src/components/comments/ (e.g. Disqus.astro) that renders a mount placeholder
2. Add a new provider branch in Comments.astro’s conditional rendering
3. Add initialization logic in src/scripts/comments.ts
4. Extend CommentProvider and config types in src/types/config.ts