评论配置

comment

评论配置，目前内置 Giscus、Twikoo、Waline、Artalk 四种评论插件。

提示

支持每个文章页配置不同的在评论区提供者 provider。

config.mts

// .vitepress/config.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  comment: {
    provider: "giscus", // 评论区提供者
    // 评论区配置项，根据 provider 不同而不同，具体看对应官网的使用介绍
    options: {
      // twikoo 配置，官网：https://twikoo.js.org/
      // envId: "your envId",

      // waline 配置，官网：https://waline.js.org/
      // serverURL: "your serverURL",
      // jsLink: "https://unpkg.com/@waline/client@v3/dist/waline.js",
      // cssLink: "https://unpkg.com/@waline/client@v3/dist/waline.css",

      // giscus 配置，官网：https://giscus.app/zh-CN
      repo: "your repo",
      repoId: "your repoId",
      category: "your category",
      categoryId: "your categoryId",

      // artalk 配置，官网：https://artalk.js.org/
      // server: "your server",
      // site: "site",
    },
  },
});

文章页 xxx.md

---
tk:
  comment:
    provider: giscus
    options:
      repo: your repo
      repoId: your repoId
      category: your category
      categoryId: your categoryId
---

更多配置项

interface TeekConfig {
  /**
   * 评论配置
   */
  comment?:
    | CommentConfig<"twikoo">
    | CommentConfig<"waline">
    | CommentConfig<"giscus">
    | CommentConfig<"artalk">
    | CommentConfig<"render">;
}

type CommentConfig<T extends keyof CommentProvider = "twikoo" | "waline" | "giscus" | "artalk" | "render"> = {
  /**
   * 评论区提供者
   * twikoo 官网：https://twikoo.js.org/
   * waline 官网：https://waline.js.org/
   * giscus 官网：https://giscus.app/zh-CN
   * artalk 官网：https://artalk.js.org/
   * render 需要自定义评论区组件，并通过 comment 插槽传入
   */
  provider: T;
  /**
   * 评论区配置项，根据 provider 不同而不同，具体看对应官网的使用介绍
   */
  options?: CommentProvider[T];
};

export type CommentProvider = {
  /**
   * twikoo 评论区配置项
   */
  twikoo: {
    /**
     * 官网其他配置项
     */
    [key: string]: any;
    envId: string;
    /**
     * twikoo.js 在线链接
     *
     * @default 'https://cdn.jsdelivr.net/npm/twikoo@{version}/dist/twikoo.nocss.js'
     */
    jsLink?: string;
    /**
     * twikoo.css 在线链接
     *
     * @default 'https://cdn.jsdelivr.net/npm/twikoo@{version}/dist/twikoo.css'
     */
    cssLink?: string;
    /**
     * twikoo 版本号，不定期更新为最新版
     *
     * @default '1.6.42'
     */
    version?: string;
    /**
     * twikoo 的 css、js 的 integrity
     */
    jsIntegrity?: string;
    /**
     * 页面渲染后多少毫秒开始渲染 twikoo，如果设置太短，可能获取的 DOM 还没加载完成
     *
     * @default 700 (0.7秒)
     */
    timeout?: number;
    /**
     * katex 配置项，如果设置，则加载 katex
     */
    katex?: {
      /**
       * katex 的 css、core、render 的在线链接
       */
      cssLink: string;
      coreJsLink: string;
      renderJsLink: string;
      /**
       * katex 的 css、core、render 的 integrity
       */
      cssIntegrity?: string;
      coreJsIntegrity?: string;
      renderJsIntegrity?: string;
    };
  };
  /**
   * waline 评论区配置项
   */
  waline: {
    /**
     * 官网其他配置项
     */
    [key: string]: any;
    /**
     * waline 后台服务器地址
     */
    serverURL: string;
    /**
     * waline.js 在线链接
     */
    jsLink?: string;
    /**
     * waline.css 在线链接
     */
    cssLink?: string;
    /**
     * waline.css 的 integrity
     */
    cssIntegrity?: string;
    /**
     * 暗黑模式，具体使用请看 waline 官网
     *
     * @default "html[class='dark']"
     */
    dark?: string;
  };
  /**
   * giscus 评论区配置项
   */
  giscus: {
    [key: string]: any;
    repo: `${string}/${string}`;
    repoId: string;
    category: string;
    categoryId: string;
    mapping?: "url" | "title" | "og:title" | "specific" | "number" | "pathname";
    strict?: "0" | "1";
    reactionsEnabled?: "0" | "1";
    emitMetadata?: "0" | "1";
    inputPosition?: "top" | "bottom";
    lang?: string;
    theme?: string;
    loading?: "lazy" | "eager";
    /**
     * 是否使用在线链接
     *
     * @default true
     */
    useOnline?: boolean;
    /**
     * giscus.js 在线链接，useOnline 为 true 时生效
     *
     * @default 'https://giscus.app/client.js'
     */
    link?: string;
    /**
     * giscus.js 的 integrity
     */
    integrity?: string;
  };
  /**
   * artalk 评论区配置项
   */
  artalk: {
    [key: string]: any;
    /**
     * artalk 后台服务器地址
     */
    server: string;
    /**
     * artalk 站点名称
     */
    site: string;
  };
  /**
   * 自定义评论组件
   */
  render: Record<string, any>;
};

如果您使用 Twikoo，你只需要传入 version 版本号即可，Teek 会根据版本号去分别请求 Twikoo 的 JS、CSS 文件，其请求地址分别为：

• JS：https://cdn.jsdelivr.net/npm/twikoo@{version}/dist/twikoo.nocss.js
• CSS：https://cdn.jsdelivr.net/npm/twikoo@{version}/dist/twikoo.css

提示

如果您无法访问 cdn.jsdelivr.net，则可以通过 jsLink 和 cssLink 配置项来手动传入链接地址，但是 Teek 建议不要传入 twikoo.all.min.js 或 twikoo.min.js 的在线链接，而是传入 twikoo.nocss.js 和 twikoo.css 在线链接。

原因：twikoo.all.min.js 或 twikoo.min.js 内部会自动引入 Twikoo 的 CSS 文件，该 CSS 文件会全局影响 Teek 的样式，因此请手动传入 twikoo.nocss.js 和 twikoo.css 在线链接，Teek 会让其样式局部生效。

评论区实例注入

在 comment 配置项里，评论区的实例都是通过传入在线 JS、CSS 链接来实现，如果网速不好或者在线链接无法访问，那么评论区会无法正常加载。

Teek 支持手动传入评论区的实例，因此您可以安装评论区的依赖，然后按照官方的 API 初始化实例后传给 Teek。

首先安装评论插件依赖（按需安装）：

# 安装 Waline 依赖
pnpm add -D @waline/client

# 安装 Giscus 依赖
pnpm add -D @giscus/vue

# 安装 Artalk 依赖
pnpm add -D artalk

然后在 .vitepress/theme/index.ts 里面注入评论区的实例。

// .vitepress/theme/index.ts
import Teek, { artalkContext, giscusContext, walineContext } from "vitepress-theme-teek";
import "vitepress-theme-teek/index.css";
import { useData, useRoute } from "vitepress";
import { init } from "@waline/client";
import "@waline/client/style";
import Giscus from "@giscus/vue";
import Artalk from "artalk";
import "artalk/Artalk.css";

export default {
  extends: Teek,
  Layout: defineComponent({
    name: "LayoutProvider",
    setup() {
      const { isDark, page } = useData();
      const route = useRoute();

      // 注入评论区实例
      provide(walineContext, (el, options) => init({ serverURL: options.serverURL!, dark: options.dark, el }));
      provide(giscusContext, () => Giscus);
      provide(artalkContext, (el, options) =>
        Artalk.init({
          el,
          darkMode: isDark.value,
          pageKey: route.path,
          pageTitle: page.value.title,
          server: options.server,
          site: options.site,
        })
      );

      return () => h(Teek.Layout, null, {});
    },
  }),
};

提示

这些依赖都是评论插件官方文档提供的，如果无法安装/注入成功，请前往对应官方文档阅读如何安装依赖、初始化实例。

最后可以把 config 里的在线链接配置项删除，当然您也可以保留，当两者同时存在，以评论区实例注入为主。

自定义评论区

如果这四个评论区提供者都不符合需求，可以自己实现评论区，然后传入进来。

先把 provider 必须指定为 render。

// .vitepress/config.mts
const teekConfig = defineTeekConfig({
  comment: {
    provider: "render", // 自定义评论区必须指定 render
  },
});

最后通过 teek-comment 插槽传入自定义评论区组件。

// .vitepress/theme/index.ts
import Teek from "vitepress-theme-teek";
import "vitepress-theme-teek/index.css";
import MyCommentComponent from "./components/MyCommentComponent.vue";
import { h } from "vue";

export default {
  extends: Teek,
  Layout() {
    return h(Teek.Layout, null, {
      "teek-comment": () => h(MyCommentComponent),
    });
  },
};