vuepress-theme-plume/知识笔记.md at bc527fdd4d4498bddb865a923e69cfca93c24dfe

yuany3721/vuepress-theme-plume

Fork 0

forked from gitea-yuany3721/vuepress-theme-plume

pengzhanbo 30adbecc8c docs: update docs

2024-09-04 00:33:56 +08:00

7.5 KiB

Raw Blame History

title, author, icon, createTime, permalink, tags

title

author

icon

createTime

permalink

概述

主题提供了 笔记 的功能，它用于聚合同一个系列的文章、或者作为站点的 子文档 。

笔记 以文件结构作为划分依据，默认以 notes/ 作为根目录，存放在 notes 目录下的文档不会作为博客文章，不会出现在博客文章列表页中。

文件结构与配置

我们有一个项目中，有以下文件结构：

::: file-tree

docs
- notes
  - typescript # typescript 笔记
    - basic.md
    - types.md
  - rust # rust 笔记
    - tuple.md
    - struct.md
- blog-post.md # 博客文章
- README.md # 站点首页

:::

在 docs/notes 目录下，有两个子目录，分别用于存放 typescript 和 rust 的系列内容。

接下来，在配置文件中配置 notes：

import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'

export default defineUserConfig({
  theme: plumeTheme({
    notes: {
      // 声明所有笔记的目录，(默认配置，通常您不需要声明它)
      dir: '/notes/',
      link: '/', // 声明所有笔记默认的链接前缀， 默认为 '/' （默认配置，通常您不需要声明它）
      notes: [
        // 每个笔记都是 `notes` 数组中的一个对象
        {
          // 声明笔记的目录，相对于 `notes.dir`，这里表示 `notes/typescript` 目录
          dir: 'typescript',
          // 声明笔记的链接前缀，与 `notes.link` 拼接，这里表示 `/typescript/`
          // 笔记内的所有文章会以 `/typescript/` 作为访问链接前缀。
          link: '/typescript/',
          // 配置 笔记侧边导航栏，用于导航向笔记内的所有文档
          // 声明为 `auto` 的，将根据目录结构自动生成侧边栏导航
          sidebar: 'auto'
        },
        {
          dir: 'rust',
          link: '/rust/',
          sidebar: [
            { text: '简介', items: ['foo'] }
          ]
        }
      ]
    }
  })
})

::: tip

你应该在创建文件之前，建议先把笔记的目录和链接前缀等配置好。主题默认启用了 auto-frontmatter，需要根据配置，为目录中的 md 文件生成永久链接，以及侧边栏。

:::

侧边栏配置

以 typescript 目录为例，它拥有如下的文件结构：

::: file-tree

typescript
- guide
  - intro.md
  - getting-start.md
- config
  - config-file.md
  - configuration.md
- reference
  - basic.md
  - syntax.md
  - modules.md
- built-in
  - types
    - Required.md
    - Omit.md
- README.md

:::

自动生成侧边栏

一种最简单的配置方式是 sidebar: 'auto' ，主题会自动根据文件结构生成侧边栏，并根据首个字符的编码来排序。

如果想要修改自动生成的侧边栏的顺序，可以直接在目录名或文件名之前，添加 1. 或 2. 等前缀。

::: file-tree

typescript
- 1.guide
  - 1.intro.md
  - 2.getting-start.md
- 2.config
  - 1.config-file.md
  - 2.configuration.md
- … :::

主题将根据这部分的前缀的数字进行排序，前缀部分不会显示在侧边栏中。

自定义侧边栏

有时候自动生成侧边栏不能完全满足需求，你可以自定义侧边栏。

以下是侧边栏的类型定义：

type Sidebar = (string | SidebarItem)[]

interface SidebarItem {
  /**
   * 侧边栏文本
   */
  text?: string

  /**
   * 侧边栏链接
   */
  link?: string

  /**
   * 侧边栏图标
   */
  icon?: ThemeIcon

  /**
   * 当前分组的链接前缀，链接前缀会拼接在 `items` 内的 `link` 之前
   * 当且仅当 `items` 内的 `link` 为 相对路径时，才会拼接
   */
  prefix?: string
  /**
   * 次级侧边栏分组
   */
  items?: 'auto' | (string | SidebarItem)[]

  /**
   * 如果未指定，组不可折叠。
   * 如果为`true`，组可折叠，并默认折叠。
   * 如果为`false`，组可折叠，但默认展开。
   */
  collapsed?: boolean
}

当传入类型为 string 时，表示 markdown 文件的路径：

const sidebar: Sidebar = [
  '/guide/intro.md',
  '/guide/getting-start.md',
  '/config/config-file.md',
  // ...
]

你也可以省略 .md 文件后缀，简写为 /guide/intro 。主题会解析对应的文件，获取标题和 页面链接地址 并将其转换为 { text: string, link: string } 的数据形式。

当传入类型为 SidebarItem 时:

const sidebar: Sidebar = [
  { text: '介绍', link: '/guide/intro' },
  { text: '快速上手', link: '/guide/getting-start' },
  // ...
]

也可以进行多层嵌套：

const sidebar: Sidebar = [
  {
    text: '指南',
    prefix: '/guide', // 使用 prefix 拼接，可以简写 下面的 items 中的 link 为相对路径
    items: [
      // 可以混用 string 和 SidebarItem
      { text: '介绍', link: 'intro' },
      'getting-start',
    ],
  },
  {
    text: '配置',
    prefix: '/config',
    items: 'auto', // items 为 'auto'，会根据 prefix 的文件结构自动生成侧边栏
  },
]

:::warning 不建议侧边栏的层级过深，超过 3 层的侧边栏可能会导致糟糕的 UI 效果。 :::

侧边栏图标

为侧边栏添加图标有助于侧边栏更好的呈现。得益于 iconify 这个强大的开源图标库，你可以使用超过 200k 的图标，仅需要添加 icon 配置即可。

const sidebar: Sidebar = [
  {
    text: '指南',
    prefix: '/guide',
    icon: 'ep:guide', // iconify icon name // [!code hl]
    items: [
      { text: '介绍', link: 'intro', icon: 'ph:info-light' }, // [!code hl]
    ],
  },
]

也可以使用本地图标，或者本地图片：

const sidebar: Sidebar = [
  {
    text: '指南',
    prefix: '/guide',
    icon: '/images/guide.png', // iconify icon name // [!code hl]
    items: [
      { text: '介绍', link: 'intro', icon: '/images/info.png' }, // [!code hl]
      // 也可以是一个远程图片
      { text: '快速上手', link: 'getting-start', icon: 'https://cn.vuejs.org/images/logo.png' },
    ],
  },
]

请注意，使用本地图片必须以 / 开头，表示为静态资源路径，它将从 .vuepress/public/ 目录中加载。

::: file-tree

docs
- .vuepress
  - public # 在这个位置保存静态资源
    - images
      - guide.png
      - info.png
- … :::

你可能已经注意到，sidebar: auto 时，该如何配置侧边栏图标，事实上很简单，直接在文件的 frontmatter 部分，添加一个 icon 字段即可。

::: code-tabs @tab typescript/guide/intro.md

---
title: 介绍
icon: ep:guide
---

:::

笔记首页

你可能注意到，在 typescript 目录下，有一个 README.md 文件，它会被作为笔记首页显示。

::: file-tree

typescript
- README.md
- …
… :::

默认情况下，它与普通的文档页面没有区别，这是因为主题默认对所有页面设置了 pageLayout: docs。

但你可以直接配置 pageLayout: 'home'，就像配置站点首页一样，为笔记配置一个个性化的首页！

::: code-tabs @tab typescript/README.md

---
pageLayout: home
config:
  - type: hero
  - type: features
---

:::

7.5 KiB Raw Blame History Unescape Escape

概述

文件结构与配置

侧边栏配置

自动生成侧边栏

自定义侧边栏

侧边栏图标

笔记首页

7.5 KiB

Raw Blame History