Comments Plugin

Add comment functionality to your VitePress documentation site.

Overview

Comments allow readers to engage with your content, ask questions, and provide feedback. There are several popular comment systems you can integrate with VitePress.

Giscus

Giscus is a comment system powered by GitHub Discussions. It's free, open source, and doesn't track users.

Installation

npm install @giscus/vue

Configuration

1. Enable Discussions on your GitHub repository
2. Install the Giscus app
3. Configure Giscus on the configuration page

Usage

Create a comment component:

<!-- .vitepress/theme/components/Comments.vue -->
<template>
  <div class="comments">
    <Giscus
      :repo="repo"
      :repo-id="repoId"
      :category="category"
      :category-id="categoryId"
      :mapping="mapping"
      :strict="strict"
      :reactions-enabled="reactionsEnabled"
      :emit-metadata="emitMetadata"
      :input-position="inputPosition"
      :theme="theme"
      :lang="lang"
      :loading="loading"
    />
  </div>
</template>

<script setup>
import Giscus from '@giscus/vue'
import { useData } from 'vitepress'

const { isDark } = useData()

const repo = 'your-username/your-repo'
const repoId = 'your-repo-id'
const category = 'General'
const categoryId = 'your-category-id'
const mapping = 'pathname'
const strict = '0'
const reactionsEnabled = '1'
const emitMetadata = '0'
const inputPosition = 'bottom'
const theme = computed(() => isDark.value ? 'dark' : 'light')
const lang = 'en'
const loading = 'lazy'
</script>

<style scoped>
.comments {
  margin-top: 2rem;
  padding-top: 2rem;
  border-top: 1px solid var(--vp-c-divider);
}
</style>

Integration

Add comments to your theme layout:

<!-- .vitepress/theme/Layout.vue -->
<template>
  <Layout>
    <template #doc-after>
      <Comments />
    </template>
  </Layout>
</template>

<script setup>
import DefaultTheme from 'vitepress/theme'
import Comments from './components/Comments.vue'

const { Layout } = DefaultTheme
</script>

Gitalk

Gitalk is a modern comment component based on GitHub Issue and Preact.

Installation

npm install gitalk

Usage

<!-- .vitepress/theme/components/Gitalk.vue -->
<template>
  <div id="gitalk-container"></div>
</template>

<script setup>
import { onMounted } from 'vue'
import { useRoute } from 'vitepress'
import Gitalk from 'gitalk'
import 'gitalk/dist/gitalk.css'

const route = useRoute()

onMounted(() => {
  const gitalk = new Gitalk({
    clientID: 'your-client-id',
    clientSecret: 'your-client-secret',
    repo: 'your-repo',
    owner: 'your-username',
    admin: ['your-username'],
    id: route.path,
    distractionFreeMode: false
  })
  
  gitalk.render('gitalk-container')
})
</script>

Disqus

Disqus is a popular hosted comment system.

Installation

npm install vue-disqus

Usage

<!-- .vitepress/theme/components/Disqus.vue -->
<template>
  <div class="disqus-container">
    <Disqus 
      :shortname="shortname"
      :identifier="identifier"
      :url="url"
    />
  </div>
</template>

<script setup>
import { Disqus } from 'vue-disqus'
import { useRoute, useData } from 'vitepress'

const route = useRoute()
const { site } = useData()

const shortname = 'your-disqus-shortname'
const identifier = route.path
const url = `${site.value.base}${route.path}`
</script>

Utterances

Utterances is a lightweight comments widget built on GitHub issues.

Usage

<!-- .vitepress/theme/components/Utterances.vue -->
<template>
  <div ref="utterancesRef" class="utterances-container"></div>
</template>

<script setup>
import { ref, onMounted, watch } from 'vue'
import { useData } from 'vitepress'

const utterancesRef = ref()
const { isDark } = useData()

const createUtterances = () => {
  const script = document.createElement('script')
  script.src = 'https://utteranc.es/client.js'
  script.setAttribute('repo', 'your-username/your-repo')
  script.setAttribute('issue-term', 'pathname')
  script.setAttribute('theme', isDark.value ? 'github-dark' : 'github-light')
  script.setAttribute('crossorigin', 'anonymous')
  script.async = true
  
  utterancesRef.value.appendChild(script)
}

onMounted(() => {
  createUtterances()
})

watch(isDark, () => {
  // Reload utterances when theme changes
  const iframe = utterancesRef.value.querySelector('iframe')
  if (iframe) {
    iframe.contentWindow.postMessage(
      {
        type: 'set-theme',
        theme: isDark.value ? 'github-dark' : 'github-light'
      },
      'https://utteranc.es'
    )
  }
})
</script>

Configuration Options

Enable/Disable Comments

Control comments per page using frontmatter:

---
comments: true
---

Custom Comment Component

Create a wrapper component that handles different comment systems:

<!-- .vitepress/theme/components/CommentSystem.vue -->
<template>
  <div v-if="showComments" class="comment-system">
    <component :is="commentComponent" />
  </div>
</template>

<script setup>
import { computed } from 'vue'
import { useData } from 'vitepress'
import Giscus from './Giscus.vue'
import Gitalk from './Gitalk.vue'
import Disqus from './Disqus.vue'

const { frontmatter, theme } = useData()

const showComments = computed(() => {
  return frontmatter.value.comments !== false
})

const commentComponent = computed(() => {
  const system = theme.value.commentSystem || 'giscus'
  
  switch (system) {
    case 'giscus':
      return Giscus
    case 'gitalk':
      return Gitalk
    case 'disqus':
      return Disqus
    default:
      return Giscus
  }
})
</script>

Best Practices

1. Choose the Right System: Consider your audience and requirements
2. Theme Integration: Ensure comments match your site's theme
3. Performance: Load comments only when needed
4. Moderation: Set up proper moderation for your comment system
5. Privacy: Consider privacy implications of third-party comment systems

Troubleshooting

Common Issues

1. Comments not loading: Check your configuration and API keys
2. Theme not switching: Implement proper theme change handlers
3. CORS errors: Ensure proper domain configuration
4. Rate limiting: Be aware of API rate limits for GitHub-based systems