Skip to content
Documentation
Configuration Overview
Comments

Comments

Configure the article comments widget. Tralume supports remark42, giscus, utterances, waline, and twikoo, and lets the widget follow the current site theme and page language where the provider supports it. By default, comment threads use the formal URL of the default language instead of being split by language-specific URLs.

Supported providers

ProviderBackendRequired keys
remark42Self-hosted Remark42host
giscusGitHub Discussionsrepo, repoId, category, categoryId
utterancesGitHub Issuesrepo
walineWaline serverserverURL
twikooTwikoo environmentenvId

Basic configuration

Set one provider in hugo.toml:

[params.comments]
  provider = 'remark42'
  # Note: Strategy used to merge comment threads.
  # Note: defaultLanguage uses the formal URL of the default language; this is the theme default.
  mergeStrategy = 'defaultLanguage'

  [params.comments.providers.remark42]
    # Note: Remark42 service URL. It must match REMARK_URL in the backend configuration.
    host = 'https://remark42.example.com'
    # Note: Site ID. It must match SITE in the Remark42 backend startup settings.
    siteId = 'my-site'

Only the selected provider is rendered. If the required keys for that provider are missing, the comments card is not rendered.

Giscus 

[params.comments]
  provider = 'giscus'
  # Note: defaultLanguage shares one discussion across translated pages.
  mergeStrategy = 'defaultLanguage'

  [params.comments.providers.giscus]
    # Note: GitHub repository that has Giscus installed.
    repo = 'owner/repo'
    # Note: Repository ID from the Giscus configuration page.
    repoId = 'R_kgDOExample'
    # Note: GitHub Discussions category name.
    category = 'Announcements'
    # Note: Category ID from the Giscus configuration page.
    categoryId = 'DIC_kwDOExample'

Optional Giscus parameters:

[params.comments.providers.giscus]
  # Note: Mapping mode. The theme default is specific, using the shared thread URL as term.
  mapping = 'specific'
  # Note: Custom term. Leave unset to use the URL generated by mergeStrategy.
  term = 'custom-thread-id'
  # Note: Enable strict title matching.
  strict = false
  # Note: Show reaction controls.
  reactionsEnabled = true
  # Note: Emit discussion metadata events.
  emitMetadata = false
  # Note: Comment input position.
  inputPosition = 'bottom'
  # Note: Giscus themes used for Tralume light/dark mode.
  lightTheme = 'light'
  darkTheme = 'dark'

Utterances 

[params.comments]
  provider = 'utterances'
  mergeStrategy = 'defaultLanguage'

  [params.comments.providers.utterances]
    # Note: GitHub repository that has Utterances installed.
    repo = 'owner/repo'

Optional Utterances parameters:

[params.comments.providers.utterances]
  # Note: Custom issue term. Leave unset to use the URL generated by mergeStrategy.
  issueTerm = 'custom-thread-id'
  # Note: Label applied to issues created by Utterances.
  label = 'comments'
  # Note: Utterances themes used for Tralume light/dark mode.
  lightTheme = 'github-light'
  darkTheme = 'github-dark'

Waline 

[params.comments]
  provider = 'waline'
  mergeStrategy = 'defaultLanguage'

  [params.comments.providers.waline]
    # Note: Waline server URL.
    serverURL = 'https://waline.example.com'

Optional Waline parameters:

[params.comments.providers.waline]
  # Note: Custom language code. Leave unset to follow the current page language.
  lang = 'en-US'
  # Note: Required metadata fields before posting a comment.
  requiredMeta = ['nick', 'mail']
  # Note: Enable reaction, pageview, and comment counters if your Waline server supports them.
  reaction = true
  pageview = true
  comment = true

Twikoo 

[params.comments]
  provider = 'twikoo'
  mergeStrategy = 'defaultLanguage'

  [params.comments.providers.twikoo]
    # Note: Twikoo environment ID or server URL, depending on your deployment target.
    envId = 'https://twikoo.example.com'

Optional Twikoo parameters:

[params.comments.providers.twikoo]
  # Note: Tencent Cloud region, only needed for Tencent CloudBase deployment.
  region = 'ap-shanghai'
  # Note: Custom language code. Leave unset to follow the current page language.
  lang = 'en'

Remark42 optional parameters 

[params.comments.providers.remark42]
  # Note: Maximum number of comments shown by default on mobile.
  maxShownComments = 20
  # Note: Whether to show the email subscription entry to visitors.
  showEmailSubscription = true
  # Note: Whether to show the RSS subscription entry to visitors.
  showRssSubscription = true
  # Note: Whether to enable a simpler interface.
  simpleView = false
  # Note: Whether to hide the Remark42 footer. Hidden by default (true); set to false to show it again.
  noFooter = true

Notes

  • The comments widget is rendered as a dedicated card after the article metadata card.
  • Remark42, Giscus, Utterances, and Waline follow the current site light/dark mode automatically. Twikoo uses its own frontend theme behavior.
  • Provider language follows the current page language where supported. The theme maps zh-Hans to zh-CN; English maps to en, except Waline uses en-US.
  • mergeStrategy = 'smartPath': merge /zh-hans/posts/test/ and /en-us/posts/test/ into one neutral thread; when defaultContentLanguageInSubdir = true the thread URL stays /posts/test/, and when defaultContentLanguageInSubdir = false with params.i18nRouting.enableAutoEntry = true it becomes /auto/posts/test/ so notification emails also land on the smart entry page first.
  • mergeStrategy = 'defaultLanguage': always use the default-language formal URL as the shared thread identifier. This is the theme default. Keep the default language at the lowest weight so Hugo’s language order stays aligned.
  • mergeStrategy = 'none': keep one independent thread per language URL.
  • Giscus defaults to mapping = 'specific', Utterances defaults to a custom issue term, and Waline/Twikoo use path; all three use the URL generated by mergeStrategy unless you override the provider-specific term/path setting.
Last updated on • alexma233
SearchFriends Links