网站LOGO
博客 | 棋の小站
页面加载中
2月21日
网站LOGO 博客 | 棋の小站
记录学习,心得,状态,生活。
菜单
  • 热评
    用户的头像
    首次访问
    上次留言
    累计留言
    我的等级
    我的角色
    打赏二维码
    打赏博主
    Vuepress-Hope折腾日记 & 搭建教程
    点击复制本页信息
    微信扫一扫
    文章二维码
    文章图片 文章标题
    创建时间
  • 一 言
    确认删除此评论么? 确认
  • 本弹窗介绍内容来自,本网站不对其中内容负责。
    按住ctrl可打开默认菜单

    Vuepress-Hope折腾日记 & 搭建教程

    · 原创 ·
    技术分享 · 实用教程
    共 10993 字 · 约 7 分钟 · 446

    文章
    摘要

    这篇文章详细记录了如何将云笔记迁移到Vuepress,并介绍了Vuepress-Hope主题的搭建过程。作者分享了在VSCode中进行操作的建议,以及安装NodeJS和pnpm包管理器的步骤。教程包括了安装Vuepress-Hope、配置导航栏和侧边栏、页面信息设置、小元素如图标和页脚的添加,以及深色模式、全屏模式和主题色的配置。文章还提到了一些默认启用的插件,以及如何使用搜索插件。整体而言,这是一篇全面而详细的Vuepress搭建教程,适用于搭建文档管理系统或个人博客。

    前几天成功将云笔记迁移至Vuepress,解决了我一个最焦虑的问题:原由Docsify驱动的云笔记不能加载favicon。当然,界面也更加好看。比起Docsify,Vuepress除了具有Docsify基本的功能(搜索、目录、代码高亮),它还支持许多功能扩展。这篇文章用于记录如何搭建Vuepress,以便日后查阅,也可作为教程观看。云笔记

    Vuepress-Hope是Vuepress的一款主题,也是NPM上下载数量最多,最多人喜欢的Vuepress主题。它受如此欢迎的原因就是它具有丰富的插件支持和功能配置,可以最大化尽可能随心所欲地搭建自己想要的站点。除了搭建成文档管理系统(云笔记),它也可以驱动为一个博客。现在有很多人使用Vuepress-Hope搭建文档和博客。查看

    官网的文档可能比较晦涩难懂,我也是研究了两天才得以将云笔记上线。它更趋向于文档,而不适合作为教程观看,因此你可以观看这篇文章从而搭建一个与我一模一样的云笔记。

    若你在阅读我的搭建教程时遇到了问题,可能是由于Vuepress-Hope主题更新导致此文章部分内容过时,这时你可以前往Vuepress-Hope官网查看文档,不过其他部分仍然可以继续观看。

    那么让我们开始吧。

    运行环境

    IDE的话,这里推荐使用VSCode,它能够很好地支持Vuepress-Hope的语法,并提供类型检查、代码补全等功能。VSCode

    除此之外,你的电脑还需要有NodeJS环境,下载最新版即可。NodeJS官网

    这里建议NodeJS过旧的升级到最新版,因为本教程是使用Vuepress-Hope最新版做演示,而他们所需要的NodeJS版本很高。

    安装完NodeJS后,建议使用pnpm包管理器,因为Vuepress-Hope的官网全部教程都是使用此包管理器,且我使用的也是。

    在终端中输入如下命令激活pnpm包管理器。

    shell 代码:
    corepack enable
    corepack prepare pnpm@latest --activate

    到这一步完成后,就可以打开PowerShell,输入pnpm,看看是否安装成功。

    验证pnpm是否配置成功验证pnpm是否配置成功

    安装Vuepress-Hope

    使用cd命令跳转到你要安装的目录,输入以下命令初始化目录,并安装Vuepress-Hope。这里我将项目安装到A盘根目录,并将文件夹命名为vuepress-demo。

    shell 代码:
    cd A:/
    pnpm create vuepress-theme-hope vuepress-demo

    在这一步后,会出现如下图所示的选择语言界面,这里可以选择使用中文。按键盘的上下键选择后,按回车确定。

    选择显示语言选择显示语言

    选择显示语言后的选项可以根据自己的需要自由设置,或者和我图中的保持一致。

    创建完成创建完成

    开始修改配置

    打开VSCode,打开创建的项目文件夹,就可以开始编辑了。

    它的项目文件夹结构如下。

    项目文件夹结构项目文件夹结构

    src为文档目录,在生成静态目录时就是渲染这个文件夹里面的markdown。.vuepress文件夹为配置和样式文件夹,public文件夹用于放置静态文件,styles用于存储样式,主题色就可以在这里面定义。config.ts为总配置文件,navbar.ts为导航栏配置,sidebar.ts为侧边栏配置,theme.ts为主题配置。在src文件夹下还有一个README.md文件,这里面存放了Vuepress-Hope为我们生成的强大主页模板,我们可以基于这个修改。

    配置导航栏

    这个在navbar.ts中配置。这里可配置的导航栏情况有以下几种,可以直接查看代码。

    typescript 代码:
    //navbar.ts
    import { navbar } from "vuepress-theme-hope";
    
    export default navbar([
      "/", /* 单链接 */
      {
        text: "V2 文档",  /* 链接、图标、链接 */
        icon: "book",
        link: "https://theme-hope.vuejs.press/zh/",
      },
      {
        text: "指南",
        icon: "lightbulb",
        prefix: "/guide/",
        children: [ /* 嵌套的链接 */
          {
            text: "Bar",
            icon: "lightbulb",
            prefix: "bar/",
            children: ["baz", { text: "...", icon: "ellipsis", link: "" }],
          },
          {
            text: "Foo",
            icon: "lightbulb",
            prefix: "foo/",
            children: ["ray", { text: "...", icon: "ellipsis", link: "" }],
          },
        ],
      },
    ]);

    之后可以打开终端预览这个界面。使用如下命令可以在localhost:8080预览。

    shell 代码:
    pnpm docs:dev
    导航栏导航栏

    如果要填写外链时,要填写链接名text和链接link,图标icon是可选的,否则主题会将其渲染为内链。

    此外,导航栏可以开启一些额外功能,如我的云笔记开启了全屏、切换主题颜色、切换夜间模式。这个在后面会介绍。

    侧边栏

    侧边栏比较复杂,详细的可以前往官方文档阅读,这里分享一下我自己的配置。我的云笔记中,比如MySQL笔记下有【基础知识】、【高级应用】等三个目录,我想在进入MySQL根目录时显示其他三个目录的标题。在点进这三个目录中的其中一个时,可以再显示这个目录内的其他目录,如下图。

    位于/MySQL/目录位于/MySQL/目录位于/MySQL/基础知识/目录位于/MySQL/基础知识/目录 typescript 代码:
    //sidebar.ts
    import { sidebar } from "vuepress-theme-hope";
    
    export default sidebar({
      '/mysql/': [
        '/mysql/基础知识/',
        '/mysql/MySQL基础/',
        '/mysql/高级应用/'
      ],
      '/mysql/基础知识/': [
        '/mysql/基础知识/认识数据库.md',
        '/mysql/基础知识/数据表操作.md',
        '/mysql/基础知识/数据库操作.md',
        '/mysql/基础知识/MySQL数据类型.md',
        '/mysql/基础知识/MySQL数据引擎.md'
      ]
    });

    再比如我的汇编速查中只有一个笔记,没有其他子目录了,我想让进入它的时候显示其他笔记,如下图。

    无子目录时显示其他笔记无子目录时显示其他笔记 typescript 代码:
    //sidebar.ts
    import { sidebar } from "vuepress-theme-hope";
    
    export default sidebar({
      '/assembly/': [
        '/assembly/',
        '/awt/',
        '/crawler/',
        '/css/',
        '/django/',
        '/fastapi/',
        '/flask/',
        '/html/',
        '/java/',
        '/javascript/',
        '/linux/',
        '/mongodb/',
        '/mysql/',
        '/nlp/',
        '/pyqt6/',
        '/python/',
        '/redis/',
        '/swing/',
        '/tornado/'
        ]
    });

    这里面这些目录的名称就是你想展示的其他目录的名称。

    这里不得不提一下,对于Vuepress的目录结构,和路由之间是有一定配合的。由于Vuepress最后构建的页面是纯静态页面,我们默认进入一个路径时访问的是index.html,它是用README.md文件渲染的,而其他路径,如【基础知识.html】就是用【基础知识.md】渲染的。所以你可以看到,我的MySQL笔记中有一些路径是以【.md】结尾的,有些则是以【/】结尾的。以【某某/】结尾的文件就相当于【某某/README.md】。

    页面信息

    每个Markdown前面可以用一些简单的YAML语法定义这个页面的信息。如title代表这个网页的名称,description则为这个网页的描述。

    如现在我改一下根目录README.md的文件,如下。

    markdown 代码:
    ---
    title: 这是网页标题
    description: 这是网页描述
    author: 作者名称
    ---
    
    ## 这是一个二级标题
    
    这是一个正文。
    渲染的网页渲染的网页

    由于这是根目录的README.md文件,因此我们往往会将其渲染为主页,这时我们可以在开始的YAML格式加一条:home: true。

    渲染成主页渲染成主页

    我们可以加一些元素,让其看起来更像主页。下面的代码是官方预设的模板代码,我将其精简了一下。

    markdown 代码:
    ---
    home: true
    icon: home
    title: 项目主页
    heroImage: /logo.svg
    bgImage: https://theme-hope-assets.vuejs.press/bg/6-light.svg
    bgImageDark: https://theme-hope-assets.vuejs.press/bg/6-dark.svg
    bgImageStyle:
      background-attachment: fixed
    heroText: 项目名称
    tagline: 你可以在这里放置或是整个项目的描述。
    actions:
      - text: 使用指南
        icon: lightbulb
        link: ./demo/
        type: primary
    
      - text: 文档
        link: ./guide/
    
    highlights:
      - header: 在 Markdown 中添加你想要的内容
        description: 我们扩展了标准的 CommonMark 规范,为你添加了成吨功能。
        image: /assets/image/markdown.svg
        bgImage: https://theme-hope-assets.vuejs.press/bg/2-light.svg
        bgImageDark: https://theme-hope-assets.vuejs.press/bg/2-dark.svg
        bgImageStyle:
          background-repeat: repeat
          background-size: initial
        features:
          - title: 链接检查
            icon: clipboard-check
            details: 检查 Markdown 链接
            link: https://theme-hope.vuejs.press/zh/guide/markdown/others.html#link-check
    
          - title: 提示容器支持
            icon: box-archive
            details: 用样式装饰 Markdown 内容
            link: https://theme-hope.vuejs.press/zh/guide/markdown/hint.html
    
          - title: GFM 警告
            icon: bell
            details: GFM 风格的警告容器
            link: https://theme-hope.vuejs.press/zh/guide/markdown/alert.html
    
          - title: 选项卡
            icon: table-columns
            details: 使用选项卡对相似内容进行分组
            link: https://theme-hope.vuejs.press/zh/guide/markdown/tabs.html
    
    copyright: true
    footer: 使用 <a href="https://theme-hope.vuejs.press/zh/" target="_blank">VuePress Theme Hope</a> 主题 | MIT 协议, 版权所有 © 2019-present Mr.Hope
    ---
    
    这是项目主页的案例。你可以在这里放置你的主体内容。
    
    想要使用此布局,你需要在页面 front matter 中设置 `home: true`。
    
    配置项的相关说明详见 [项目主页配置](https://theme-hope.vuejs.press/zh/guide/layout/home/)。
    让主页更丰富让主页更丰富

    建议为每个页面都配置title,这样网页就可以显示正确的标题,否则它会将markdown的第一个一级标题作为网页的标题。

    其他小元素

    图标

    这里我将图标改为了Remixicon。它给的图标库有iconfont、fontawesome等。

    首先参照我的使用图标为网页增添小细节下载Remixicon图标库,然后将其内容解压,放在/src/public/remixicon/文件夹下,然后在theme.ts中添加如下项。

    remixiconremixicon typescript 代码:
    //theme.ts
    import { hopeTheme } from "vuepress-theme-hope";
    import navbar from "./navbar.js";
    import sidebar from "./sidebar.js";
    
    export default hopeTheme({
      //...
      iconAssets: "/remixicon/remixicon.css",
      iconPrefix: 'ri-',
      //...
    });

    接下来,将要添加的图标处加一个icon: iconname,就可以添加图标了,如为之前导航栏配置的主页添加一个房子的图标。

    typescript 代码:
    //navbar.ts
    import { navbar } from "vuepress-theme-hope";
    
    export default navbar([
      {
        text: "主页",  /* 链接、图标、链接 */
        icon: "home-line",
        link: "/",
      }
    ]);
    添加图标添加图标

    页脚

    页脚可以展示版权信息,备案号等。首先需要在theme.ts中设置displayFooter: true。footer是页脚默认内容,支持HTML语法,就可以在这里面输入链接。

    typescript 代码:
    //theme.ts
    import { hopeTheme } from "vuepress-theme-hope";
    import navbar from "./navbar.js";
    import sidebar from "./sidebar.js";
    
    export default hopeTheme({
      footer: "<a href='https://example.com'>备案号: xxxx</a>",
      displayFooter: true,
    });

    由于这里面设置的是默认页脚,在上方展示的首页markdown中也有一个footer的选项,这个页脚配置会将theme.ts中的页脚配置覆盖掉,这一点要注意。

    页脚展示页脚展示

    在页脚右方的是版权信息,这个也是在theme.ts中配置,用copyright配置。同样,它也会被markdown的内容覆盖掉。

    typescript 代码:
    //theme.ts
    import { hopeTheme } from "vuepress-theme-hope";
    import navbar from "./navbar.js";
    import sidebar from "./sidebar.js";
    
    export default hopeTheme({
      copyright: '版权信息',
    });

    深色模式、全屏模式

    在theme.ts中设置darkmode的值以更改,它有以下几个值:

    • "switch": 在深色模式,浅色模式和自动之间切换 (默认)
    • "toggle": 在深色模式和浅色模式之间切换
    • "auto": 自动根据用户设备主题或当前时间决定是否应用深色模式
    • "enable": 强制深色模式
    • "disable": 禁用深色模式

    全屏模式则可以在theme.ts中设置fullScreen: true。

    主题色

    在/src/.vuepress/public/pallete.scss中可以设置主题色,修改$theme-color的值即可。

    除此之外,还可以设置多个主题色,以在导航栏中激活选择主题色。这需要修改/src/.vuepress/public/config.scss的中$theme-color的值。如:

    scss 代码:
    $theme-colors: #c0392b, #d35400, #f39c12, #27ae60, #16a085, #2980b9, #8e44ad, #2c3e50,
      #7f8c8d;
    设置主题色设置主题色

    插件

    搜索功能

    首先先在shell中运行下面的脚本,添加搜索插件。

    shell 代码:
    pnpm add -D vuepress-plugin-search-pro

    然后在config.ts中添加如下代码。

    typescript 代码:
    // .vuepress/config.ts
    import { defineUserConfig } from "vuepress";
    import { searchProPlugin } from "vuepress-plugin-search-pro";
    
    export default defineUserConfig({
      plugins: [
        searchProPlugin({
          // 索引全部内容
          indexContent: true,
          // 为分类和标签添加索引
          customFields: [
            {
              getter: (page) => page.frontmatter.category,
              formatter: "分类:$content",
            },
            {
              getter: (page) => page.frontmatter.tag,
              formatter: "标签:$content",
            },
          ],
        }),
      ],
    });

    为标签和分类添加索引这个在我的云笔记中没有添加,因为我用不到。

    默认启用的插件

    Vuepress-Hope内置了一些插件,这些插件是默认启用的,你可以在配置文件中手动它他们关闭。

    • 代码复制:vuepress-theme-hope 将主题选项中的 plugins.copyCode 选项作为插件选项提供给 vuepress-plugin-copy-code2。若你不需要这个插件,在theme.ts的plugin中将这个值设为false即可,下面的插件亦是如此。
    • 图片预览:vuepress-theme-hope 将主题选项中的 plugins.photoSwipe 选项作为插件选项提供给 vuepress-plugin-photo-swipe。
    • 版权:vuepress-theme-hope 将主题选项中的 plugins.copyright 作为插件选项提供给 vuepress-plugin-copyright2。该插件不是默认启用的。

    其他配置

    在theme.ts文件中存在一些其他的配置,鼠标悬浮于上面可以显示它们的详细信息。

    悬浮在hostname上时出现的提示悬浮在hostname上时出现的提示

    官方文档也对这些变量做了详细的解释。

    声明:本文由 (博主)原创,依据 CC-BY-NC-SA 4.0 许可协议 授权,转载请注明出处。

    还没有人喜爱这篇文章呢

    现在已有

    10

    条评论
    发一条!
    1. 头像
      obaby
      • 等级:Lv.4
      • 角色:综合 · 好友
      • 在线:本月

      折腾使人充实

      · · · 山东-青岛
      1. 头像
        obaby

        云笔记好看吧?

        · · · 河北-秦皇岛
    2. 头像
      白雾茫茫丶
      • 等级:Lv.2
      • 角色:访客
      • 在线:三月内

      你是真的能折腾呀,有空就是好,啥都能捣鼓一下

      · · · 广东-深圳
      1. 头像

        哈哈,最近没课,就有空研究这些,也快放假了。

        · · · 河北-秦皇岛
    3. 头像
      Dabenshi
      • 等级:Lv.2
      • 角色:访客
      • 在线:三月内

      周一忙什么呢,快出来摸鱼了

      · · · 北京-北京
      1. 头像
        Dabenshi

        啊?我们现在没课,天天在被窝打游戏

        · · · 河北-秦皇岛
    4. 头像
      TeacherDu
      • 等级:Lv.5
      • 角色:首页 · 好友
      • 在线:本月

      你这边也有相关留言吗?

      · · · 北京-北京
      1. 头像
        TeacherDu

        有,不过之前全面加强了评论审核,现在一个也没有了。

        · · · 河北-秦皇岛
    5. 头像
      云晓晨CatchYun
      • 等级:Lv.5
      • 角色:首页 · 好友
      • 在线:本月

      前来拜访

      · · · 山东-济南
      1. 头像

        欢迎欢迎

        · · · 河北-石家庄
    博客logo 博客 | 棋の小站 记录学习,心得,状态,生活。
    ICP 冀ICP备2023007665号

    🕛

    本站已运行 299 天 11 小时 46 分

    🌳

    建站:Typecho 主题:MyLife

    👁️

    今日访问量:1622 昨日访问量:1607
    棋の小站 © 2024.
    网站logo

    博客 | 棋の小站 记录学习,心得,状态,生活。
     
     
     
     
    壁纸