Vitepress 杂谈 ｜ 青训营笔记

Freaky_Forward
1,132 阅读9分钟

这是我参与「第五届青训营」伴学笔记活动的第8天。

网站的一系列配置

在 docs/.vitepress/config.ts 中可以进行网站的一系列配置。

Vitepress 基本可配置内容简介：

VitePress有两种主要配置和一个 Frontmatter 配置。 一个是AppConfigs，它配置站点的基本功能。应用程序配置可用于定义站点的全局设置。应用程序配置定义的基本设置不仅限于主题配置，例如“基本目录”的配置或网站的“标题”。 第二个是 ThemeConfig，它配置站点的主题，例如，添加侧边栏，或添加“在GitHub上编辑此页面”链接等功能。

配置 TS 智能提示功能

TS 智能提示功能有两种配置方式： 一个是通过 jsdoc type 形式的提示。

/**
 * @type {import('vitepress').UserConfig}
 */
const config = {
  // ...
}

export default config

另一个是通过 从 vitepress 中导入 {defineConfig} Type 类型包裹配置项的形式使用 TS 类型提示。

关于 {defineConfig} 使用的类型提示声明： defineConfig Type Helper 类型默认使用 Vitepress 的 themeConfig 配置项，如果你有自定义的主题配置项，可以用以下方式引用： defineConfigWithTheme<YourThemeConfig>

import { defineConfigWithTheme } from 'vitepress'
import { YourThemeConfig } from 'your-theme'

export default defineConfigWithTheme<YourThemeConfig>({
  themeConfig: {
    // Type is `ThemeConfig`
  }
})

Theme Configs

可配置项有：

  1. i18nRouting
    1. Vitepress 实现 i18n 的方式是根据选择的语言进行不同语言页面替换的方式实现的
  2. logo
    1. 要在导航栏中显示的徽标文件，就在网站标题之前。接受路径字符串或对象以设置不同的亮/暗模式徽标。
  3. siteTitle
    1. 您可以自定义此项以替换nav中的默认站点标题（app-config中的标题）。当设置为false时，导航中的标题将被禁用。当您的徽标已经包含网站标题文本时，这很有用。
  4. nav
    1. 导航菜单项的配置。您可以在Theme: Nav中了解更多详细信息。
  5. sidebar
    1. 侧边栏菜单项的配置。您可以在Theme: Sidebar.了解更多。
  6. aside
    1. 将此值设置为false将阻止渲染备用容器。
  7. outline
    1. 要在大纲中显示的标题级别。您可以通过传递数字来指定特定级别，也可以通过传递包含下限和上限的元组来提供级别范围。当传递等于[2，6]的'deep'时，除h1外，所有标题级别都显示在大纲中。设置false以隐藏轮廓。
  8. outlineBadges
    1. 默认情况下，徽章文本显示在大纲中。禁用此选项可从大纲中隐藏徽章文本。
  9. outlineTitle
    1. 可用于自定义右侧边栏的标题（在大纲链接的顶部）。这在用另一种语言编写文档时很有用。
  10. socialLinks
    1. 您可以定义此选项以在导航中显示带有图标的社交帐户链接。
    2. Vitepress 包涵了一系列默认 Icons。
  11. footer
    1. 页脚配置。您可以在页脚上添加消息或版权文本，但是，只有当页面不包含侧边栏时才会显示。这是由于设计问题。
  12. editLink
    1. 编辑链接允许您在GitHub或GitLab等Git管理服务上显示编辑页面的链接。有关详细信息，请参见 Theme: Edit Link。
  13. lastUpdatedText
    1. 在上次更新时间之前显示的前缀文本。
  14. algolia
    1. 支持使用Algolia DocSearch.搜索文档站点的选项。在Theme: Search中了解更多信息。
  15. docFooter
    1. 可用于自定义出现在上一个和下一个链接上方的文本。如果不是用英语写文档，会很有用。
  16. darkModeSwitchLabel
    1. 可用于自定义暗模式开关标签。此标签仅显示在移动视图中。
  17. sidebarMenuLabel
    1. 可用于自定义侧边栏菜单标签。此标签仅显示在移动视图中。
  18. return To TopLabel
    1. 可用于自定义returnToTop的标签。此标签仅显示在移动视图中。

App Configs

可配置项有：

  1. appearance
    1. 它还注入了内联脚本，该脚本尝试通过vitebress主题外观键从本地存储读取用户设置，并恢复用户首选的颜色模式。
  2. base
    1. 网站将部署在的基本URL。如果您计划在子路径（例如GitHub页面）下部署网站，则需要设置此URL。如果您计划将站点部署到foo.github.io/bar/，则应将基数设… base，因此只需指定一次。
  3. description
    1. 站点说明。这将在页面HTML中呈现为＜meta＞标记。
  4. head
    1. 要在页面HTML的<head>标记中呈现的其他元素。用户添加的标记在结束头标记之前呈现，在VitePress标记之后呈现。
  5. ignoreDeadLinks
    1. 当设置为true时，VitePress不会因死链接而导致构建失败。当设置为localhostLinks时，构建将在死链接上失败，但不会检查本地主机链接。
  6. lang
    1. 站点的lang属性。这将在页面html中呈现为<html lang=“en-US”>标记。
  7. lastUpdated
    1. 使用gitcommit获取时间戳。此选项启用默认主题以显示页面的上次更新时间。您可以通过themeConfig.lastUpdatedText自定义文本。
  8. markdown
    1. 配置Markdown解析器选项。VitePress使用 Markdown-it作为解析器，Shiki突出显示语言语法。在该选项中，您可以传递各种与Markdown相关的选项以满足您的需求
  9. outDir
    1. 站点的构建输出位置，相对于项目根目录（如果您正在运行 vitepress build docs，则为docs文件夹）。
  10. cacheDir
    1. 缓存文件的目录，相对于项目根目录（如果您正在运行vitebress build docs，则为docs文件夹）。cacheDir.
  11. srcDir
    1. 存储markdown页面的目录，相对于项目根目录。
  12. title
    1. 站点的标题。这将显示在导航栏中。也用作所有页面标题的后缀，除非定义了titleTemplate。
  13. title Template
    1. 标题的后缀。例如，如果将title设置为VitePress，并将titleTemplate设置为My Site，则html标题将变为VitePress| My Site。设置为false将禁用该功能。如果选项未定义，则将使用title选项的值。
    2. 要配置除|以外的标题分隔符，可以省略title并在titleTemplate中使用：title符号。
  14. cleanUrls
    1. 允许从URL中删除尾随的.html。
    2. Warning: 启用此功能可能需要在宿主平台上进行其他配置。要使其工作，服务器必须在请求/foo时提供/foo.html，而无需重定向。
  15. rewrites
    1. 定义自定义目录<->URL映射。有关详细信息，请参阅路由：Routing: Customize the Mappings
  16. Build Hooks
    1. VitePress构建挂钩允许您向网站添加新功能和行为.

Frontmatter配置

Frontmatter支持基于页面的配置。在每次标记时，您可以自由添加任何设置来覆盖任何全局应用程序或主题配置。此外，有些配置只能在Frontmatter中定义。

可配置项有：

  1. title
    1. 页面标题。它与config.title相同，并覆盖应用程序配置。
  2. title Template
    1. 标题的后缀。它与config.titleTemplate相同，并覆盖应用程序配置。
  3. description
    1. 页面的说明。它与config.description相同，并覆盖应用程序配置。
  4. head
    1. 指定要注入的额外头标记：
  5. lastUpdated
    1. 是否在当前页面中显示上次更新的文本。
  6. layout
    1. 确定页面的布局。
    2. doc-它将默认文档样式应用于markdown内容。
    3. home-“主页”的特殊布局。您可以添加额外的选项，如英雄和功能，以快速创建漂亮的登录页面。
    4. 页面-行为类似于文档，但它对内容不应用样式。当您想要创建完全自定义的页面时非常有用。
  7. hero
    1. 此选项仅在布局设置为主页时生效。
  8. features
    1. 此选项仅在布局设置为主页时生效。
  9. aside
    1. 如果希望不显示文档布局中的右侧组件，请将此选项设置为false。
  10. outline
    1. 要为页面显示的大纲中的标题级别。它与config.themeConfig.outline,相同，并覆盖主题配置。

Theme - Team Page

  1. Show team members in a page
    1. 您可以使用从vitebress/theme公开的<VPTeamMembers>组件在任何页面上显示团队成员列表。html格式
  2. Create a full Team Page
    1. 您可以创建一个完整的团队页面，而不是将团队成员添加到文档页面，这与您创建自定义主页的方式类似。要创建团队页面，首先创建一个新的md文件。文件名不重要，但在这里我们将其称为team.md。在此文件中，设置frontmatter选项layout:page，然后可以使用TeamPage组件组成页面结构。
    2. 创建完整的团队页面时，请记住使用<VPTeamPage>组件包装所有组件。此组件将确保所有嵌套的与团队相关的组件都获得适当的布局结构，如间距<VPPageTitle>组件添加页面标题部分。标题为<h1>标题。使用#title和#lead-slot记录您的团队<VPMembers>的工作原理与在文档页面中使用时相同。它将显示成员列表。
    3. 添加分区以划分团队成员。
    4. 您可以在团队页面中添加“部分”。例如，您可能有不同类型的团队成员，如核心团队成员和社区合作伙伴。您可以将这些成员划分为多个部分，以更好地解释每个组的角色。为此，请将<VPTeamPageSection>组件添加到我们之前创建的team.md文件中。
  3. <VPTeamMembers>
    1. <VPTeamMembers>组件显示给定的成员列表。
  4. <VPTeamPage>
    1. 创建完整团队页面时的根组件。它只接受一个插槽。它将为所有传入的团队相关组件设置样式。
  5. ＜VPTeamPageTitle>
    1. 添加页面的“标题”部分。最好在<VPTeamPage>下开始使用。它接受#title和#lead-slot。
  6. <VPTeamPageSection>
    1. 在团队页面中创建一个“section”。它接受#title、#lead和#memberslot。您可以在<VPTeamPage>中添加任意数量的分区。
avatar
文章
阅读
粉丝