img

butterfly自定义页面流程

突发奇想想自定义一下页面，遂写博客记之。

原理：

当你使用 hexo new page Pagename 命令创建页面时，Hexo 会在 Blog/source/Pagename/index.md 中生成一个基础的 Markdown 文件。在这个文件中，你可以通过添加 type: "categories" 等字样来指定页面的类型。这样做的目的是告诉 Hexo 的主题（例如 Butterfly），这个页面是一个特殊类型的页面，比如分类页面、标签页面、友链页面等。

打开themes/butterfly/layout/page.pug文件，

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
extends includes/layout.pug

block content
  #page
    if top_img === false
      h1.page-title= page.title
case page.type
  when 'tags'
    include includes/page/tags.pug
  when 'link'
    include includes/page/flink.pug
  when 'categories'
    include includes/page/categories.pug
  when 'stars'
    include includes/page/stars.pug
  default
    include includes/page/default-page.pug

if page.comments !== false && theme.comments && theme.comments.use
  - var commentsJsLoad = true
  !=partial('includes/third-party/comments/index', {}, {cache: true})

1. themes/butterfly/layout/page.pug 文件结构

在 themes/butterfly/layout/page.pug 文件中，主题定义了如何处理不同类型的页面。文件的结构如下：

  • extends includes/layout.pug: 这个语句继承了一个名为 layout.pug 的布局文件，确保页面包含网站的基本布局，如头部、脚部等。
  • block content: 定义了页面主体内容的区域。所有页面特有的内容都会在这里进行渲染。
  • #page: 一个页面的包裹元素，可能用于应用通用的样式或布局。
  • if top_img === false: 如果页面的顶部图片设置为 false，则显示页面的标题。
  • case page.type: 这是一个 case 语句，用于根据页面的 type 来选择合适的模板文件来渲染页面。

2. 特殊页面的处理

当 Hexo 识别到页面的 type 是某个特殊值时，它会进入对应的模板渲染。例如：

  • when 'tags': 如果页面的类型是 tags，Hexo 会包含并渲染 includes/page/tags.pug 文件，显示页面的内容。
  • when 'link': 如果页面的类型是 link，Hexo 会使用 includes/page/flink.pug 文件渲染。
  • when 'categories': 对于 type: "categories" 的页面，Hexo 会渲染 includes/page/categories.pug 文件。
  • when 'stars': 对于 type: "stars" 的页面，Hexo 会渲染 includes/page/stars.pug 文件。
  • default: 如果页面的 type 不属于上述任何一种，Hexo 会使用 includes/page/default-page.pug 作为默认模板文件来渲染页面。

3. 评论功能

在页面渲染的最后一部分，代码检查了是否需要加载评论功能：

  • if page.comments !== false && theme.comments && theme.comments.use: 如果页面没有禁用评论，且主题启用了评论功能，则加载评论部分。
  • !=partial('includes/third-party/comments/index', {}, {cache: true}): 通过 partial 命令，渲染第三方评论插件的模板，并缓存结果以提高性能。

核心是第二部分。

开始构建

创建页面

详细解释

1. 创建特殊页面

首先，通过命令 hexo new page stars 创建一个新的页面，Hexo 会在 source/stars/index.md 文件中生成该页面的基本结构。为了让这个页面被主题识别为特殊页面，你需要在 index.md 文件的头部（Front Matter）中添加 type: "stars"，这告诉主题这个页面将使用特定的布局。

1
2
3
4
---
title: stars
type: "stars"
---

2. 定义布局文件

接下来，在主题的布局目录中（themes/butterfly/layout/includes/page），新建一个名为 stars.pug 的文件。这个文件决定了 stars 页面如何呈现。

3. 构建stars.pug文件

在 stars.pug 中，页面结构使用了 Pug 语法，这是一个 HTML 模板引擎。以下是 stars.pug 的详细解释：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
.flink#article-container
    if site.data.stars
        each i in site.data.stars
            if i.class_name
                h2!= i.class_name
            if i.class_desc
                .flink-desc!=i.class_desc
            .flink-list
                each item in i.link_list
                    .flink-list-item
                        a(href=url_for(item.link)  title=item.name target="_blank")
                            - var urlNoProtocol = item.link.replace(/^https?\:\/\//i, "")
                            - var imgUrl = "https://api.iowen.cn/favicon/" + urlNoProtocol + ".png"
                            img.flink-avatar.entered.loaded(src=url_for(imgUrl) onerror=`this.onerror=null;this.src='` + url_for(theme.error_img.flink) + `'` alt=item.name)
                            .img-alt.is-center= item.name
                            .flink-item-info
                                span.flink-item-name= item.name
                                span.flink-item-desc(title=item.descr)= item.descr
    != page.content

4. 代码解释

  • .flink#article-container: 定义一个容器，ID为 article-container，并使用 flink 样式。

  • if site.data.stars: 检查数据文件中是否存在 stars 数据。site.data.stars 通常是通过一个 YAML 或 JSON 文件定义的，你可以在 source/_data/stars.yml 中管理这些数据。

  • each i in site.data.stars: 遍历 stars 数据中的每个分类（如 设计素材, 工具网站 等）。

    • if i.class_name: 如果分类数据中存在 class_name 字段，则输出一个二级标题 (h2)，内容为该分类的名称。

    • if i.class_desc: 如果分类数据中存在 class_desc 字段，则输出一段描述。

    • .flink-list: 为该分类创建一个列表容器。

      • each item in i.link_list: 遍历分类下的链接列表 link_list。

        • .flink-list-item: 为每个链接项创建一个列表元素。

          • a(href=url_for(item.link) title=item.name target="_blank"): 创建一个链接标签，链接到 item.link，并设置链接的标题和打开方式（在新窗口打开）。

          • img.flink-avatar.entered.loaded: 为链接项添加一个图标。这里使用的是通过 API 动态生成的 Favicon 图标。

          • .flink-item-info: 包含链接名称和描述信息的容器。

            • span.flink-item-name: 显示链接的名称。

            • span.flink-item-desc: 显示链接的描述，当描述过长时，提供了 title 属性以便用户悬停查看完整描述。

  • != page.content: 输出页面的 Markdown 内容，允许在 index.md 中添加额外的内容。

引入页面

正如前面所说，需要引入才会被主题识别，修改themes/butterfly/layout/page.pug文件，注意对齐

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
extends includes/layout.pug

block content
  #page
    if top_img === false
      h1.page-title= page.title

    case page.type
+     when 'stars'
+        include includes/page/stars.pug
      when 'tags'
        include includes/page/tags.pug
      when 'link'
        include includes/page/flink.pug
      when 'categories'
        include includes/page/categories.pug
      default
        include includes/page/default-page.pug

    if page.comments !== false && theme.comments && theme.comments.use
      - var commentsJsLoad = true
      !=partial('includes/third-party/comments/index', {}, {cache: true})

添加内容

新建source/_data/stars.yml文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
- class_name: 设计素材
  class_desc: 为你的设计添加色彩
  list_style: butterfly
  link_list:
    - name: Font Awesome
      link: https://fontawesome.com/
      descr: 一个基于CSS和LESS的字体和图标工具包
    - name: Iconfont
      link: https://www.iconfont.cn/
      descr: 阿里巴巴矢量图标库
    - name: Flaticon
      link: https://www.flaticon.com/
      descr: 海量扁平化免费的图标库
    - name: Ficon8
      link: https://www.flaticon.com/authors/ficon8
      descr: 独特系统平台风格和web图标库，下载免费图标
    - name: WebGradients
      link: https://webgradients.com/
      descr: 渐变色搭配方案
    - name: CoolHue
      link: https://webkul.github.io/coolhue/
      descr: 渐变色搭配方案

- class_name: PPT素材
  class_desc: 提供免费PPT模板素材
  list_style: butterfly
  link_list:
    - name: 第一PPT
      link: https://www.diyippt.com/
      descr: 第一PPT，提供免费PPT模板素材
    - name: PPT超级市场
      link: https://www.pptsupermarket.com/
      descr: PPT超级市场，提供免费PPT模板素材

- class_name: 工具网站
  class_desc: 各种有用的工具和资源
  list_style: butterfly
  link_list:
    - name: Free Logo Design
      link: https://www.freelogodesign.org/
      descr: 在线Logo设计网站
    - name: 表情速查
      link: https://www.emojiall.com/
      descr: 在线表情素材网站
    - name: LottieFiles
      link: https://lottiefiles.com/
      descr: 免费提供各种样式的加载动画gif等
    - name: EMOJIALL
      link: https://www.emojiall.com/
      descr: 多语言 EMOJI词典，这里有关于Emoji、Emoji含义、Emoji图片等的所有信息
    - name: TinyPNG
      link: https://tinypng.com/
      descr: WebP/PNG/JPEG图片在线压缩利器
    - name: EZGIF
      link: https://ezgif.com/
      descr: 在线PNG转WebP格式图片
    - name: Loading
      link: https://loading.io/
      descr: 制作GIF、SVG、CSS加载动画图标
    - name: removebg
      link: https://www.remove.bg/
      descr: 一键智能在线抠图

- class_name: 程序员工具
  class_desc: 工具箱、代码处理等
  list_style: butterfly
  link_list:
    - name: 程序员的工具箱
      link: https://toolbox.yourwebsite.com/
      descr: 站长工具、代码格式化、压缩、加密、解密等
    - name: 记磊工具箱
      link: https://toolbox.jilei.com/
      descr: DNS检测、CSS格式化、超级Ping、端口扫描等
    - name: 孟坤工具箱
      link: https://toolbox.mengkun.com/
      descr: CSS一键美化、文本差异比较、代码高亮等
    - name: OSCHINA.NET社区
      link: https://www.oschina.net/
      descr: 常用文档、常用对照表、代码处理、HTML/CSS/JS工具、加密转换等
    - name: TOOLTT
      link: https://tooltt.com/
      descr: 常用各种语言格式转换，支持html转pug格式

- class_name: 开源镜像站
  class_desc: 提供开源软件及系统镜像下载
  list_style: butterfly
  link_list:
    - name: 阿里巴巴开源镜像站
      link: https://developer.aliyun.com/mirror/
      descr: 阿里巴巴开源镜像站，OPSX镜像站，开源软件，系统镜像，镜像下载
    - name: 清华大学开源镜像站
      link: https://mirrors.tuna.tsinghua.edu.cn/
      descr: 清华大学开源软件镜像站，致力于为国内和校内用户提供高质量的开源软件镜像、Linux 镜像源服务
    - name: Z-Library
      link: https://z-lib.org/
      descr: 世界上最大的电子图书馆。自由访问知识和文化。

页面效果参考：收藏 | Totoroの旅 (totorocatcat.top)

文章参考：butterfly自定义页面流程，一通百通 | ELIX的博客² (elixsion.github.io)

Butterfly如何自定义页面，简单明了！创建自己的网站收藏页面 | JayHrn (lvhrn.cn)