xfmpress Published on 2026-11-21

Comments: One Plugin, Ten Comment Services

8 min read # xfmpress# tutorial

One plugin, ten comment services

Adding comments to a static site doesn't take ten plugins — xfm-plugin-comments unifies ten comment services behind a single comments.provider switch:

providerNotesRequired config
giscusGitHub Discussions based, the go-to for dev blogsrepo, repoId, category, categoryId
beaudarGitHub Issues based, Chinese-friendlyrepo
utterancesThe original GitHub Issues commentsrepo
disqusEstablished international serviceshortname
walineSelf-hosted, friendly for China accessserverURL
twikooSelf-hosted, lightweightenvId
valineLeanCloud basedappId, appKey
gitalkAnother GitHub Issues implementationclientID, clientSecret, repo
artalkSelf-hosted, multi-site managementserver
cusdisPrivacy-friendly, no trackingappId, host

Install and configure

npm i -D xfm-plugin-comments
// xfm.config.mjs
export default {
  comments: {
    provider: 'giscus',        // switch services by changing one line
    repo: 'xfm0797/xfm0797.github.io',
    repoId: 'R_kgDOxxxxxxx',
    category: 'Announcements',
    categoryId: 'DIC_kwDOxxxxxxx',
  },
  // ...
};

Switching services only touches provider and its required fields — no theme template changes.

What a thread binds to: identifier

comments.identifier decides what a comment thread binds to:

  • path (default) — binds to the URL path; changing paths "loses" comments
  • url — binds to the full URL (with domain), good for multi-domain setups
  • title — binds to the page title; comments follow the title however the URL changes

Required-field validation: skip, don't ship broken widgets

Missing required fields such as repoId / envId makes the plugin warn and skip mounting instead of injecting a component guaranteed to error; an unknown provider lists the supported names. Builds never fail — the log tells you what's missing.

Stylesheets on demand

Services that ship their own styles (Waline, Gitalk, Artalk) get their CSS injected into <head> only on pages that actually mount the widget — listing and archive pages stay lean.

Page-level switch

---
comments: false   # no comment section on this page (about / links pages)
---

Theme mounting point

By default the plugin injects the whole section before </article>. To choose the position yourself, leave an empty container carrying data-xfm-comments in the template — the plugin then only adds the scripts and never builds a second container:

{% if site.comments %}
<section class="post-comments">
  <h2 class="section-title">{{ page.lang == 'en' ? 'Comments' : '评论' }}</h2>
  <!-- Waline looks for #waline, so a custom container needs the id -->
  <div id="waline" data-xfm-comments></div>
</section>
{% endif %}

This site (xfmpress-theme-anziyu) mounts it under the post card; the config lives in the comments block of xfm.config.mjs:

comments: {
  provider: 'waline',
  serverURL: 'https://waline.xfm.qzz.io',   // no trailing slash — a "/" yields //api/... and a 308 redirect
  lang: 'zh-CN',
  login: 'enable',
  requiredMeta: ['nick', 'mail'],
  commentSorting: 'newest',
}
Multilingual sites

comments.lang is a site-wide constant, so English pages do not switch the widget's UI by themselves. This site ships a dozen-line local plugin (plugins/comments-lang.js) that rewrites lang inside init({...}) to page.lang during transformHtml; threads still stay separate because they are keyed by path (/xxx/ vs /en/xxx/).

Coming from xfm-plugin-giscus? No config changes needed — the package was renamed but the provider: 'giscus' config key is unchanged; just install xfm-plugin-comments.


Next: Math and Diagrams — build-time KaTeX and Mermaid rendering.

Comments