One

主题

插件配置 ​

vitePlugins ​

内置 Vite 插件配置。

Teek 内置的 Vite 插件详细介绍请看 Vite 插件。

ts
// .vitepress/config.ts
import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    sidebar: true, // 是否启用 sidebar 插件
    sidebarOption: {}, // sidebar 插件配置项
    permalink: true, // 是否启用 permalink 插件
    permalinkOption: {}, // permalinks 插件配置项
    mdH1: true, // 是否启用 mdH1 插件
    catalogueOption: {}, // catalogues 插件配置项
    docAnalysis: true, // 是否启用 docAnalysis 插件
    docAnalysisOption: {}, // docAnalysis 插件配置项
    fileContentLoaderIgnore: [], // fileContentLoader 插件扫描 markdown 文档时，指定忽略路径，格式为 glob 表达式，如 **/test/**
    autoFrontmatter: true, // 是否启用 autoFrontmatter 插件
    // autoFrontmatter 插件配置项
    autoFrontmatterOption: {
      permalinkPrefix: "pages", // 自动生成 permalink 的固定前缀，如 pages、pages/demo，默认为 pages
      categories: true, // 是否自动生成 categories
      // ...
    },
  },
});
ts
import type { PermalinkOption } from "vitepress-plugin-permalink";
import type { SidebarOption } from "vitepress-plugin-sidebar-resolve";
import type { CatalogueOption } from "vitepress-plugin-catalogue";
import type { DocAnalysisOption } from "vitepress-plugin-doc-analysis";
import type { AutoFrontmatterOption } from "plugins/vitepress-plugin-auto-frontmatter";

interface TkThemeConfig {
  /**
   * 内置 Vite 插件配置
   */
  vitePlugins?: Plugins;
}

interface Plugins {
  /**
   * 是否启用 sidebar 插件
   *
   * @default true
   */
  sidebar?: boolean;
  /**
   * sidebar 插件配置项
   */
  sidebarOption?: SidebarOption;
  /**
   * 是否启用 permalink 插件
   *
   * @default true
   */
  permalink?: boolean;
  /**
   * permalinks 插件配置项
   */
  permalinkOption?: PermalinkOption;
  /**
   * 是否启用 mdH1 插件
   *
   * @default true
   */
  mdH1?: boolean;
  /**
   * catalogues 插件配置项
   */
  catalogueOption?: CatalogueOption;
  /**
   * 是否启用 docAnalysis 插件
   *
   * @default true
   */
  docAnalysis?: boolean;
  /**
   * docAnalysis 插件配置项
   */
  docAnalysisOption?: DocAnalysisOption;
  /**
   * fileContentLoader 插件扫描 markdown 文档时，指定忽略路径，格式为 glob 表达式，如 test/**
   *
   * @default []
   */
  fileContentLoaderIgnore?: string[];
  /**
   * 是否启用 autoFrontmatter 插件
   *
   * @default false
   */
  autoFrontmatter?: boolean;
  /**
   * autoFrontmatter 插件配置项，并拓展出其他配置项
   *
   * permalinkPrefix 为自动生成 permalink 的固定前缀，如 pages、pages/demo，默认为 page。当禁用 permalink 插件后，不会自动生成 permalink
   * categories 为是否自动生成 categories
   *
   * @default '{ permalinkPrefix: "pages", categories: true }'
   */
  autoFrontmatterOption?: AutoFrontmatterOption & { permalinkPrefix?: string; categories?: boolean };
}

markdown ​

您可以对 Teek 内置的 Markdown 容器进行一些配置。

Teek 内置的 Markdown 插件详细介绍请看 Markdown 拓展。

config ​

通过该 config 函数来加载更多的 Markdown-it 插件。

危险

请不要在使用 Vitepress 提供 markdown.config 函数来加载 Markdown-it 插件，因为 Vitepress 方式会覆盖主题内置的 Markdown-it 插件。

ts
// .vitepress/config.ts
import defineTeekConfig from "vitepress-theme-teek/config";
import myMdPlugin from "my-md-plugin";

const teekConfig = defineTeekConfig({
  markdown: {
    config: md => {
      md.use(myMdPlugin);
    },
  },
});
ts
import type MarkdownIt from "markdown-it";

Markdown {
  /**
   * 注册更多 markdown 插件函数
   */
  config?: (md: MarkdownIt) => void;
}

container ​

Teek 内置的 Markdown 容器配置，配置项如下：

ts
interface Markdown {
  /**
   * 内置 markdown 容器的 Label 配置
   */
  container?: {
    /**
     * 自定义容器标题
     */
    label?: {
      /**
       * note 容器的默认标题
       *
       * @default 'NOTE'
       */
      noteLabel?: string;
    };
    /**
     * 自定义 markdown 容器配置
     */
    config?: () => {
      /**
       * 容器类型
       */
      type: string;
      /**
       * 是否使用标题
       */
      useTitle?: boolean;
      /**
       * 默认标题
       */
      defaultTitle?: string;
      /**
       * 容器类名
       */
      className?: string;
    }[];
  };
}

容器配置 ​

Note 容器默认的标题是 Note，您可以通过修改其默认值，这在国际化环境下很有帮助：

ts
// .vitepress/config.ts
import defineTeekConfig from "vitepress-theme-teek/config";
import myMdPlugin from "my-md-plugin";

const teekConfig = defineTeekConfig({
  markdown: {
    container: {
      label: {
        noteLabel: "笔记",
      },
    },
  },
});

自定义容器 ​

Teek 支持自定义 Markdown 容器配置。

通过 markdown.container.config 函数可以快速创建出类似于 Teek 内置的 center 和 right 容器或 Vitepress 的 info、tip、warning、danger 容器。

先看例子：

ts
// .vitepress/config.ts
import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  markdown: {
    container: {
      config: () => [
        { type: "demo1", useTitle: true, defaultTitle: "demo1", className: "demo1-container" },
        { type: "demo2", useTitle: false, className: "demo2-container" },
      ],
    },
  },
});

示例中，我们创建了两个容器，其中第一个容器 demo1 通过 useTitle: true 来支持输入标题，如果不输入标题，则使用默认标题 demo1。

容器使用如下：

markdown
::: demo1
测试 demo1 容器
:::

::: demo1 容器标题
测试 demo1 容器
:::

::: demo2
测试 demo2 容器
:::

生成的 HTML 结构如下：

html

<div class="demo1 demo1-container">
  <p class="title demo1-title demo1-container-title">demo1</p>
  <p>测试 demo1 容器</p>
</div

<div class="demo1 demo1-container">
  <p class="title demo1-title demo1-container-title">容器标题</p>
  <p>测试 demo1 容器</p>
</div

<div class="demo2 demo2-container">
  <p>测试 demo2 容器</p>
</div

HTML 模板如下：

html
<div class="${type} ${className}">
  <p class="title ${type}-title ${className}-title">${defaultTitle || 传入标题}</p>
  <p>${输入的内容}</p>
</div
html
<div class="${type} ${className}">
  <p>${输入的内容}</p>
</div

虽然 Teek 按照 HTML 模板进行渲染，但是并没有提供 CSS 样式，您需要对 class 来自定义样式，如：

scss
// .vitepress/theme/style/container.scss
.demo1-container {
  font-size: 16px;
  .title {
    font-size: 18px;
  }
}

.demo2-container {
  font-size: 12px;
}

然后引入样式文件：

ts
// .vitepress/theme/index.ts
import Teek from "vitepress-theme-teek";
import "vitepress-theme-teek/index.css";
import "./style/container.scss";

export default {
  extends: Teek,
};

demo ​

markdown.demo 用于配置 Demo 容器，如果您不了解什么是 Demo 容器，请看 Demo 容器。

ts
// .vitepress/config.ts
import defineTeekConfig from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  markdown: {
    demo: {
      path: "examples", // Demo 组件路径，基于 .vitepress 目录层级添加
      playgroundUrl: "", // Playground 链接
      playgroundMainFileName: "App.vue", // Playground 主文件名
      githubUrl: "", // Github 链接
      playgroundButtonTip: "在 Playground 中编辑", // 鼠标悬浮 Playground 按钮提示
      githubButtonTip: "在 Github 中编辑", // 鼠标悬浮 Github 按钮提示
      copyButtonTip: "复制代码", // 鼠标悬浮复制代码按钮提示
      collapseSourceButtonTip: "查看源代码", // 鼠标悬浮查看源代码按钮提示
      expandSourceButtonTip: "隐藏源代码", // 鼠标悬浮隐藏源代码按钮提示
    },
  },
});
ts
interface Markdown {
  /**
   * demo 插件配置
   */
  demo?: {
    /**
     * Demo 组件路径，基于 .vitepress 目录层级添加
     *
     * @default 'examples'
     */
    path?: string;
    /**
     * Playground 链接
     */
    playgroundUrl?: string;
    /**
     * Playground 主文件名
     *
     * @default 'App.vue'
     */
    playgroundMainFileName?: string;
    /**
     * Github 链接
     */
    githubUrl?: string;
    /**
     * 鼠标悬浮 Playground 按钮提示
     *
     * @default '在 Playground 中编辑'
     */
    playgroundButtonTip?: string;
    /**
     * 鼠标悬浮 Github 按钮提示
     *
     * @default '在 Github 中编辑'
     */
    githubButtonTip?: string;
    /**
     * 鼠标悬浮复制代码按钮提示
     *
     * @default '复制代码'
     */
    copyButtonTip?: string;
    /**
     * 鼠标悬浮复查看源代码按钮提示（代码块处于折叠状态）
     *
     * @default '查看源代码'
     */
    collapseSourceButtonTip?: string;
    /**
     * 鼠标悬浮复查看源代码按钮提示（代码块处于展开状态）
     *
     * @default '隐藏源代码'
     */
    expandSourceButtonTip?: string;
  };
}

Demo 容器的按钮组默认有 4 个按钮：

  • 支持查看源代码
  • 复制源代码
  • 去 Github 编辑
  • 去 Playground 编辑

如果您想自定义一些按钮，可以在 .vitepress/theme/index.ts 下使用如下插槽：

  • teek-demo-code-button-left：按钮组最左边插槽
  • teek-demo-code-button-right：按钮组最右边插槽

如：

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

export default {
  extends: Teek,
  Layout() {
    return h(Teek.Layout, null, {
      "teek-demo-code-button-left": () => h(MyButton),
    });
  },
};