hexo官方文档

butterfly帮助文档

butterfly官方文档

Hexo介绍

Hexo 是一个基于 Node.js 的快速、简洁且高效的静态博客框架，常被用来搭建个人博客或技术博客。以下是对 Hexo 的简单介绍：

核心特点

  1. 静态站点生成： Hexo 可以将 Markdown 文件转换为静态的 HTML 页面，这些页面可以直接部署到静态文件托管服务（如 GitHub Pages、Netlify）。
  2. 速度快： Hexo 使用 Node.js 提供高效性能，支持快速生成成千上万篇文章的静态文件。
  3. 支持 Markdown： 使用简单且流行的 Markdown 语法撰写文章，提升写作效率。
  4. 主题丰富： Hexo 社区提供了大量主题，可以通过配置文件快速切换，满足不同用户的个性化需求。
  5. 插件生态： Hexo 拥有丰富的插件库，可扩展功能如 SEO 优化、RSS 支持、站点地图生成等。
  6. 支持多种部署方式： 内置一键部署到 GitHub Pages、GitLab Pages 或其他静态文件托管服务。

Hexo 的基本工作流程

  1. 安装 Hexo： 使用 npm 安装 Hexo：

    1
    npm install -g hexo-cli

  2. 初始化博客项目： 在本地创建一个新的 Hexo 项目：

    1
    2
    3
    hexo init my-blog
    cd my-blog
    npm install

  3. 撰写文章： 使用以下命令生成新文章并编辑：

    1
    hexo new "文章标题"

    编辑生成的 Markdown 文件 source/_posts/文章标题.md。

  4. 本地预览： 启动本地服务器预览博客效果：

    1
    hexo server

    访问 http://localhost:4000 查看。

  5. 生成静态文件： 使用以下命令生成静态页面：

    1
    hexo generate

  6. 部署到线上： 使用以下命令部署博客（例如 GitHub Pages）：

    1
    hexo deploy

文件结构

Hexo 项目的主要文件结构如下：

  • source/：存放博客内容（文章、页面等）。
  • themes/：存放主题文件。
  • _config.yml：全局配置文件，用于设置博客基本参数。
  • scaffolds/：存放文章模板。
  • public/：生成的静态页面，部署时上传的内容。

适用场景

  • 个人博客：轻松管理和发布个人文章。
  • 技术博客：结合主题和插件，可以美观展示代码片段、数学公式等。
  • 静态网站：可以用于搭建简单的静态网站，如文档网站、公司主页等。

总之，Hexo 是一个易于上手、高效且功能丰富的静态博客工具，非常适合初学者和开发者使用。

创建文章

命令行中输入：

1
$ hexo new "new article"

之后在source/_posts目录下面，多了一个new-article.md的文件。

打开之后我们会看到：

1
2
3
4
5
---
title: new article
date: 2014-11-01 20:10:33
tags:
---

文件的开头是属性，采用统一的yaml格式，用三条短横线分隔。下面是文章正文。

文章的正文支持markdown格式，采用markdown语法编写。

新建、删除或修改文章后，不需要重启hexo server，刷新一下即可预览。

font-matter

Front-matter 是 markdown 文件最上方以 —- 分隔的区域，用于指定个别档案的变数。

  • Page Front-matter 用于 页面 配置
  • Post Front-matter 用于 文章页 配置

介绍不同

在 Hexo 中，Page Front-matter 和 Post Front-matter 都是 YAML 格式的元数据，用于定义页面或文章的属性。然而，它们的用途和适用范围有所不同。以下是两者的主要区别：

1. Page Front-matter

适用范围

  • Page 是通过 hexo new page <name> 命令创建的，主要用于生成独立页面，例如关于页面（About）、标签页面（Tags）、分类页面（Categories）等。

常见用途

  • 定义独立页面的属性，例如标题、是否显示侧边栏、顶部图片等。
  • 一般用于非博客文章类的内容。

常见字段

以下字段在 Page Front-matter 中更常用：

  • title: 页面标题。
  • date: 页面创建日期。
  • type: 页面类型（如标签、分类或友情链接页面需要配置）。
  • description: 页面描述。
  • aside: 是否显示侧边栏。
  • top_img: 页面顶部图片。

  • comments: 是否显示评论模块。

    示例

1
2
3
4
5
title: About Me
date: 2024-11-26
description: 这是关于我的页面
comments: false
aside: true

2. Post Front-matter

适用范围

  • Post 是通过 hexo new <post-name> 命令创建的，主要用于博客文章。

常见用途

  • 定义文章的元信息，例如标题、发布时间、标签、分类等。

  • 针对博客内容，可以用于 SEO、文章排序、分类导航等功能。

    常见字段

以下字段在 Post Front-matter 中更常用：

  • title: 文章标题。
  • date: 文章创建日期。
  • updated: 文章更新日期。
  • tags: 文章标签（可以是数组或字符串）。
  • categories: 文章分类（可以是多级分类）。
  • description: 文章摘要。
  • keywords: 文章关键词。
  • top: 置顶权重（数值越高优先级越高）。
  • cover: 文章封面图片。
  • excerpt: 自定义文章摘要内容。

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
title: Hello Hexo
date: 2024-11-26
updated: 2024-11-27
tags:
  - Hexo
  - Blogging
categories:
  - Technology
  - Web Development
description: 如何用 Hexo 创建博客。
keywords: Hexo,博客,教程
top: 1
cover: /images/hello-hexo-cover.jpg

主要区别总结

特性 Page Front-matter Post Front-matter
用途 独立页面（关于、标签等） 博客文章
命令 hexo new page <name> hexo new <post-name>
字段 偏向页面布局和功能控制（aside, type 等） 偏向内容属性和分类（tags, categories, top 等）
适合场景 独立功能页面、非文章内容 博客内容，具有标签、分类和时间序列属性的文章

如果你需要创建一个用于展示博客内容的页面（如归档、分类），应使用 Page Front-matter；如果是日常博客内容，选择 Post Front-matter 更合适。

page front markdown

如果标注可选的参数，可根据自己需要添加，不用全部都写在 markdown 里

Page Front-matter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
---
title:
date:
updated:
type:
comments:
description:
keywords:
top_img:
mathjax:
katex:
aside:
aplayer:
highlight_shrink:
random:
limit:
  type:
  value:
---
参数 解释
title 【必需】页面标题
date 【必需】页面创建日期
type 【必需】标签、分类和友情链接三个页面需要配置
updated 【可选】页面更新日期
description 【可选】页面描述
keywords 【可选】页面关键字
comments 【可选】显示页面评论模块 (默认 true)
top_img 【可选】页面顶部图片
mathjax 【可选】显示 mathjax (当设置 mathjax 的 per_page: false 时，才需要配置，默认 false)
katex 【可选】显示 katex (当设置 katex 的 per_page: false 时，才需要配置，默认 false)
aside 【可选】显示侧边栏 (默认 true)
aplayer 【可选】在需要的页面加载 aplayer 的 js 和 css, 请参考文章下面的音乐配置
highlight_shrink 【可选】配置代码框是否展开 (true/false) (默认为设置中 highlight_shrink 的配置)
random 【可选】配置友情链接是否随机排序（默认为 false）
limit 【可选】配置説説显示数量
limit.type 【可选】配置説説显示数量的类型 （date 或者 num）
limit.value 【可选】配置説説显示数量的值

Post Front-matter

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
---
title:
date:
updated:
tags:
categories:
keywords:
description:
top_img:
comments:
cover:
toc:
toc_number:
toc_style_simple:
copyright:
copyright_author:
copyright_author_href:
copyright_url:
copyright_info:
mathjax:
katex:
aplayer:
highlight_shrink:
aside:
abcjs:
noticeOutdate:
---
写法 解释
title 【必需】文章标题
date 【必需】文章创建日期
updated 【可选】文章更新日期
tags 【可选】文章标签
categories 【可选】文章分类
keywords 【可选】文章关键字
description 【可选】文章描述
top_img 【可选】文章顶部图片
cover 【可选】文章缩略图 (如果没有设置 top_img, 文章页顶部将显示缩略图，可设为 false/图片地址/留空)
comments 【可选】显示文章评论模块 (默认 true)
toc 【可选】显示文章 TOC (默认为设置中 toc 的 enable 配置)
toc_number 【可选】显示 TOC 编号 (默认为设置中 toc 的 number 配置)
toc_style_simple 【可选】显示 TOC 简洁模式
copyright 【可选】显示文章版权模块 (默认为设置中 post_copyright 的 enable 配置)
copyright_author 【可选】文章版权模块的文章作者
copyright_author_href 【可选】文章版权模块的文章作者链接
copyright_url 【可选】文章版权模块的文章链接
copyright_info 【可选】文章版权模块的版权声明文字
mathjax 【可选】显示 MathJax (当设置 mathjax 的 per_page: false 时，才需要配置，默认 false)
katex 【可选】显示 KaTeX (当设置 katex 的 per_page: false 时，才需要配置，默认 false)
aplayer 【可选】在需要的页面加载 aplayer 的 JS 和 CSS，请参考文章下面的音乐配置
highlight_shrink 【可选】配置代码框是否展开 (true/false) (默认为设置中 highlight_shrink 的配置)
aside 【可选】显示侧边栏 (默认 true)
abcjs 【可选】加载 abcjs (当设置 abcjs 的 per_page: false 时，才需要配置，默认 false)
noticeOutdate 【可选】文章过期提醒 (默认为设置中 noticeOutdate 的 enable 配置)

更改preloader

所得教程

增加侧边栏闪刀动画

官方教程

个人实现：

你可以按照提供的指导创建一个自定义的 widget 来展示你喜欢的动图。以下是具体的步骤和代码示例。

  1. 创建 widget.yml 文件

需要在博客目录(不是butterfly主题目录)中的 source/_data 文件夹中创建一个 widget.yml 文件。如果该文件夹不存在，请先创建它。

  1. 编写 widget.yml 内容

需要在 widget.yml 中定义新的 widget，可以将其放在 bottom 中，这样这个 widget 就会显示在除文章页外的所有页面。你可以根据需要来定义各种参数，如 class_name、id_name、name、icon 和 html。

以下是一个展示自己喜欢的动图的例子：

1
2
3
4
5
6
7
top:
  - class_name: gif-widget
    id_name: gif-display
    name: SkyStriker
    icon: fas fa-film
    order: 1
    html: '<img src="/images/zhenshandao.gif" alt="SkyStriker" style="max-width:100%; height:auto;" />'
  • class_name: 设置 widget 的父类名称，比如 favorite-gif，方便你添加自定义 CSS。
  • id_name: 设置 widget 的父类 id 名称，比如 favorite-gif-widget。
  • name: widget 的标题，比如 “动图展示”。
  • icon: 图标的类名，这里我使用了 FontAwesome 的 fas fa-images 图标，你可以选择你喜欢的图标。
  • order: 排序，数字越小越靠前，数字越大越靠后。
  • html: 放置你的动图代码，使用 <img> 标签来插入你喜欢的动图，URL 替换为你的动图链接。
  1. 添加自定义 CSS (潜在想法)

如果你想对这个 widget 的样式进行定制化设计，可以在 _config.butterfly.yml 中通过 inject 添加自定义 CSS。例如：

1
2
3
inject:
  head:
    - '<link rel="stylesheet" href="/css/custom.css">'

然后，你可以创建 source/css/custom.css 文件，添加自定义样式：

1
2
3
4
5
6
7
8
9
10
11
.favorite-gif {
  background: #f5f5f5; /* 设置背景颜色 */
  border-radius: 8px; /* 设置圆角 */
  padding: 15px; /* 设置内边距 */
  text-align: center; /* 文字和动图居中对齐 */
}

.favorite-gif-widget img {
  max-width: 100%; /* 确保动图宽度不超过 widget 宽度 */
  height: auto; /* 保持宽高比 */
}
  1. 运行 Hexo

配置完成后，可以在命令行中运行 Hexo 来生成和查看效果：

1
2
3
hexo clean
hexo g
hexo s

在本地服务器 (http://localhost:4000) 查看效果，确保动图正常显示在侧边栏中。

最终效果

添加完 widget.yml 并进行 Hexo 生成后，你会看到侧边栏新增了一个模块，标题为“SkyStriker”，并且可以展示喜欢的动图。

如果你想展示多个动图，可以修改 html 中的内容，添加多个 <img> 标签。例如：

1
html: '<img src="https://your-gif-url.com/your-favorite1.gif" alt="Gif 1" style="width:100%;"><br/><img src="https://your-gif-url.com/your-favorite2.gif" alt="Gif 2" style="width:100%;">'

这样你就能在侧边栏里一次性展示多张动图。