hexo-theme-faradays 主题概述

hexo-theme-faradays 主题诞生于一个偶然的机会，当时博主正在考虑建立一个博客，因此点开了很久之前关注的 hexo 官网，并初始化了这个博客；可是博主搜了很多网站，并没有找到合适的主题，看了好久，基于颜值选了 hexo-theme-miho 来进行魔改，慢慢地，就有了这个主题。我喜欢它，希望你也能够从中得到启发。

项目概要

• 创建于: 2020/07/05 08:23:50 0.0.0

• 项目名称： Faradays 〔明月〕

• 设计理念：立足现在，放眼未来。

• 许可协议：请遵守 GPLv3 协议，侵权必究！

  Licensed under GNU GPLv3.

  You may send your request to imhhj@vip.qq.com and wait for your License Confirmation email.

  See https://www.gnu.org/licenses/gpl-3.0.html or https://choosealicense.com/licenses/gpl-3.0/ for the license details.

  

hexo 基础知识

hexo 的内置程序

安装 hexo 程序后，默认应该包含以下程序：

程序	用途	备注
hexo	主程序
hexo-deployer-git	实现 git 部署方式
hexo-generator-archive	存档页面生成器
hexo-generator-category	分类页面生成器
hexo-generator-index	index 生成器
hexo-generator-tag	标签页面生成器
hexo-renderer-ejs	支持 EJS 渲染
hexo-renderer-marked	Markdown 引擎
hexo-renderer-stylus	支持 stylus 渲染
hexo-server	本地服务器	默认地址 localhost:4000

新安装的依赖包，保存在 node_module 文件夹下。

hexo 的内置变量

hexo 内置了一些内部变量，为进一步定制开发提供了重要的基础；最重要的是 site 变量如下：

site = {
  posts: [object object], // 包含文章对象的数组
  pages: [object object], // 包含页面对象的数组
  categories: [object object], // 包含分类对象的数组
  tags: [object object] // 包含标签对象的数组
}

• 我们可以通过 JavaScript 调用 site 变量获取站点的文章总数，标签总数和分类总数。例如：

    console.log(site.pages)

• 可以在 .ejs 中获取相关变量：

  • <% code %>：用于执行其中javascript代码。
  • <%= code %>：会对code进行html转义；
  • <%- code %>：不会进行转义，

• 也可以在 shell 中查看相关变量的值：

    # 查看当前文章、独立页等情况
    hexo list [ page | post | route |tag | category ]

• 如果需要查看 hexo 内置了哪些内部变量、内部函数，可以访问以下链接：

  • Tommy Chen, HEXO官方文档.hexo 变量[EB/OL].https://hexo.io/zh-cn/docs/variables.html, 2020/08/22.

  • Tommy Chen, HEXO官方文档.hexo 辅助函数（Helpers）[EB/OL].https://hexo.io/zh-cn/docs/helpers, 2020/08/22.

模板定制的理论基础

Hexo provides the Swig template engine by default, but you can easily install additional plugins to support alternative engines such as EJS, Haml, Jade, or Pug. Hexo chooses the template engine based on the file extension of the template (just like the posts). For example:

layout.ejs   # uses EJS
layout.swig  # uses Swig

By default, the layout template is used by all other templates. You can specify additional layouts in the front-matter or set it to false to disable it. It’s even possible to build a complex nested structure by including more layout templates in your top layout.

Every layout file should contain a body variable to display the contents of the template in question. Partials are useful for sharing components between your templates. Typical examples include headers, footers or sidebars. You may want to put your partials in separate files to make maintaining your website significantly more convenient.

在模板中，举例说来，<%- partial('partial/header', {title: 'Hello World'}) %> 一句在直接导入 partial/header.ejs 的同时，同时也将该文件中定义的 title 变量赋值为 Hello World 。Partials 模板就等同于模板中定义了一个子函数一样，使得模板能够灵活地使用编程技术动态组态。

模板	用途	回退	layout_id
index	首页		0 分页导航：1
archive	归档	index	2
category	分类归档	archive	3
tag	标签归档	archive	4
post	文章	index	5
page	独立页	index	20 时间轴：21 画册：22

layout.ejs 是整个页面的入口，所有的页面都共用 layout.ejs 布局。通过 layout 之后，则根据页面的类型，将相应的内容自动添加到 HMTL 的body 当中。

因此，各个布局的 ejs 文件并没有引入 layout.ejs 当中，因此也就无法引用其定义的变量，只能通过独立页增加一个变量来进行识别。

page.layout

布局名称	用途	备注
timeline	时间轴
index	分页导航
fancybox	相册

样式定制的理论基础

Hexo ignores hidden files and files or folders prefixed with _ (underscore).

1. 在 themes\faradays\source\css\_partial 中，由于文件夹以下划线起始，hexo在编译的时候就会略过他们不生成具体的css 。也就是说最后只会生成 css 目录中不以下划线开头的名字对应的CSS文件，如 style.css 、 timeline.css 、 tocbot.css ，而不会生成诸如 _layout/footer.css 这样的文件了。

2. 根据 https://hexo.io/zh-cn/api/renderer 的说明，themes\faradays\source\css 中 style.styl 是样式总入口文件，其是受到 node_modules\hexo-renderer-stylus\index.js 文件的调用生成 css 文件的，将 .styl 生成为同名的 .css 文件、而 _ 开头的文件则不会生成，其一般都是引用到 style.styl 文件中而生成 style.css 文件。

   • _variables.styl：变量定义
   • _extend.styl：补充扩展
   • style.styl：总样式
     • _util/*.styl：不生成样式文件的局部样式定义，已在 style.styl 中 @import。
     • _partial/*.styl：不生成样式文件的局部样式定义，已在 style.styl 中 @import；不过额外创建子文件，也需要人工补充 @import 到 style.styl 文件。
   • tocbot.styl：目录样式
   • timeline.styl：时间轴样式
   • github.min.css：css样式，原样输出
   • fonts：FontAwesome 字体，在 _variables.styl 中定义了字体路径变量 font-icon-path，并在 style.styl 使用。

3. 添加 styl 文件的方法：

   • 在 themes\faradays\source\css 中增加相应的文件 xxx1.styl即可生成 xxx1.css 的独立样式文件；
   • 如果增加 _xxx2.styl，并在同目录的style.styl 中 @import xxx2，那么就会整合到 style.css 中。
   • 定义变量，如$main_color = convert(hexo-config("stylus.main_color"))；使用变量，如rgba($main_color,0.3) 或 $main_color。

hexo-theme-faradays 主题

以下简称“Faradays 主题”，主题的内容主要是包含布局、样式等内容，具体见后续逐一解剖——

Faradays 主题的模板

Faradays 主题目前使用 hexo-renderer-ejs 管理布局文件，相关文件结构如下：

layout
│-- archive.ejs      // 存档，在 **_archive/** 目录下进一步定义
│-- category.ejs
│-- index.ejs        // 首页，在 **_index/** 目录下进一步定义
│-- layout.ejs       // 公共样式（页头、页眉、页脚、侧边栏等），在 **_layout/** 目录下进一步定义
│-- post.ejs         // 文章页，在 **_post/** 目录下进一步定义
│-- tag.ejs
│-- page.ejs         // 独立页（仅设置统一样式），在 **_page/** 目录下进一步定义
│-- timeline         // 独立页（时间轴）
│-- <some_page>      // 独立页（其他，个性化样式），在 **_<some_page>/** 目录下进一步定义

根据 hexo layout 的特征，对 Faradays 主题的文件结构可以概括为， themes\faradays\layout 根目录下的每一个 .ejs 文件，都对应于一个以 _为前缀的同名文件夹来配套定义其具体布局。

Faradays 主题除了 index、archive、post 等传统布局统一设置外，主要是设置了独立的 page 布局，为进一步定制更多功能提供了可能性。比如说，时间轴就是其中的一种独立布局样式。 archive 、 category 、 tag 等共享布局的文件，也进行了解耦，更利于后期进一步精细调整、减少交叉干涉的影响程度。

page 样式虽然和 post 样式基本接近，不过代码高亮等由于插件预定义的设置问题，还是存在一些细微的差异。

测试表明，更改 ejs 、 styl 文件，不需要重新生成网站就能显示最新效果。
更为重要的是，修改 .md 格式的文章，保存后刷新就生效。

Faradays 主题的样式

默认情况下，生成一个 site.css 总文件，后续每新增独立 page 布局，就设置一个独立的 .css。他们都由 hexo-renderer-stylus 将同名的 .styl 文件转换生成。

代码高亮支持的语言

<% if (is_post()  || is_page()){ %>
    <link rel="stylesheet" href="/css/github.min.css">
<% }  %>

language 可参考 https://github.com/highlightjs/highlight.js/blob/master/SUPPORTED_LANGUAGES.md 了解。笔者比较熟悉的有 autohotkey、bash、sh、zsh、basic、csharp、cs、c、h、cpp、hpp、c++、h++、cmake、css、cisco、d、dos、bat、cmd、delphi、pas、pascal、diff、patch、django、jinja、dockerfile、docker、dts(Device Tree)、dust、excel、xls、xlsx、fortran、go、golang、groovy、xml、html、xhtml、rss、atom、xsl、svg、http、https、haskell、ini、json、java、jsp、javascript、js、kotlin、tex(LaTeX)、less、lisp、lua、makefile、mk、make、markdown、md、mathematica、mma、matlab、nginx、nginxconf、objectivec、objc、php、php7、perl、txt、pgsql、powershell、ps、ps1、properties、python、py、profile、python-repl、pycon、r、rpm、ruby、rb、rust、rs、SAS、sas、sql、shell、console、stylus、styl、swift、tcl、tk、twig、typescript、ts、vbnet、vb、vba、vbscript、vbs、vim、yml、yaml。

建议使用 bash 而不是使用 shell 。

新版 JavaScript 库在 https://github.com/highlightjs/highlight.js/releases 中下载。不过在个人测试中未能通过。

hexo 文章的书写

hexo 博客文章页可以像 reStructuredText 文章一样，灵活地增加特定格式的文本，而无须通过 .EJS 模板文件进行预定义。

1. 按照 Markdown 语法编写文章。

2. 参考 https://hexo.io/zh-cn/docs/tag-plugins 使用 hexo 特有的标签语法扩展文章的书写方式。

   • 在文章中插入引言，可包含作者、来源和标题。

     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque hendrerit lacus ut purus iaculis feugiat. Sed nec tempor elit, quis aliquam neque. Curabitur sed diam eget dolor fermentum semper at eu lorem.

     [author[source]] [link] [source_link_title]

   • 在文章中插入代码。

     code snippet

     • 特殊地，也可以将 source/downloads/code （在 _config.yml 中定义的 code_dir 路径 ）文件夹内的代码文件插入：{% include_code [title] [lang:language] [from:line] [to:line] path/to/file %}。示例如下：

       • 嵌入 test.js 文件全文：{% include_code lang:javascript test.bat %}

         :: test.bat （需要保存为 ANSI 编码后双击运行）
         @echo off
         echo 当前路径的完整字符串：%0
         echo 去掉引号：%~0
         echo 所在分区：%~d0
         echo 所处路径：%~p0
         echo 文件名：%~n0
         echo 扩展名：%~x0
         echo 文件属性：%~a0
         echo 修改时间：%~t0
         echo 文件大小：%~z0
         
         echo.
         pause

       • 只嵌入第 3 行:：{% include_code lang:javascript from:3 to:3 test.bat %}

         echo 当前路径的完整字符串：%0

       • 嵌入第 5 行至第 8 行：{% include_code lang:javascript from:5 to:8 test.bat %}

         echo 所在分区：%~d0
         echo 所处路径：%~p0
         echo 文件名：%~n0
         echo 扩展名：%~x0

       • 嵌入第 5 行至文件结束：{% include_code lang:javascript from:5 test.bat %}

         echo 所在分区：%~d0
         echo 所处路径：%~p0
         echo 文件名：%~n0
         echo 扩展名：%~x0
         echo 文件属性：%~a0
         echo 修改时间：%~t0
         echo 文件大小：%~z0
         
         echo.
         pause

       • 嵌入第 1 行至第 8 行：{% include_code lang:javascript to:8 test.bat %}

         :: test.bat （需要保存为 ANSI 编码后双击运行）
         @echo off
         echo 当前路径的完整字符串：%0
         echo 去掉引号：%~0
         echo 所在分区：%~d0
         echo 所处路径：%~p0
         echo 文件名：%~n0
         echo 扩展名：%~x0

   • 在文章中插入 iframe ：{% iframe url [width] [height] %}。

   • 在文章中插入指定大小的图片（需要绝对路径）：{% img [class names] /path/to/image [width] [height] '"title text" "alt text"' %}。

     

   • 在文章中插入链接，并自动给外部链接添加 target=”_blank” 属性： {% link text url [external] [title] %}。

     text url [external] [title]

   • 引用其他文章的链接： {% post_path filename %} 或 {% post_link filename [title] [escape] %}。

     Post not found: zh-CN_20200607_chang-log

     • 在使用此标签时可以忽略文章文件所在的路径或者文章的永久链接信息、如语言、日期。

       例如，在文章中使用 Post not found: hexo-theme-faradays_summary 时，只需有一个名为 hexo-theme-faradays_summary.md 的文章文件即可。即使这个文件位于站点文件夹的 source/posts/hexo-theme-faradays_summary 目录下、或者文章的永久链接是 2018/zh-CN/hexo-theme-faradays_summary，都没有影响。

     • 默认链接文字是文章的标题，你也可以自定义要显示的文本。

     • 默认对文章的标题和自定义标题里的特殊字符进行转义。可以使用escape选项，禁止对特殊字符进行转义。

   • 引用文章的资源： {% asset_path filename %}、{% asset_img [class names] slug [width] [height] [title text [alt text]] %}、{% asset_link filename [title] [escape] %}。

   • 使用 Raw 标签，以免发生解析异常：content。

   • 文章摘要和截断：在文章中使用 ，那么 之前的文字将会被视为摘要。首页中将只出现这部分文字，同时这部分文字也会出现在正文之中。

3. Faradays 主题内置了一些 Front-matter 字段，概况如下：

字段	含义	备注
author2	第 2 作者
author3	第 3 作者
author_x	其他作者
original	文章原创指数	如 100%
keywords	文章关键词	jQuery,JavaScript
site_banner	站点横幅
post_banner	文章横幅

author2: Ivy Faraday
author3: unknown
author_x: 
    - ['Bat Man', 'https://faradays-studio.github.io/']
    - ['Iron Man', 'https://faradays-studio.github.io/']

4. 对于特殊字符进行转义，举例如下：

   • {: {

   • }: }

使用注意事项

1. 文章的 Front-matter 中的数字应当使用引号包围，才能形成字符；如果需要转换为数字，可以使用相应的 JavaScript 转换函数。

研究总结

独立页的功能测试

1. 测试表明，独立页面使用 hexo 内置的渲染有以下特点（.md 文件直接放相应的目录下，不做任何特殊处理，系统原生使用 layout: page 渲染）：

   • 不支持标签、分类。
   • 生成的 .HTML 名称是 .md 文件名，与默认的 _post 目录下的文件按项目配置文件 _config.yml 中定义的 permalink 格式是有明显区别的。
   • 相关页面不会被索引到首页、归档页，也不会进入使用 site.posts 循环读取的时间轴页上。
   • 个人感觉：使用 hexo 的 Front-matter 指定的标题样式比使用 h1 配置要合适一点（因为默认的 h1 渲染出来的文字太大了！！！）
   • 独立页面中的链接的 .html 扩展名不能删除，也不会被裁减。
   • 在页面中定义 permalink 、 path 等均毫无意义，独立页仍然使用 :title（文件名）.html 作为连接名（实际上，个人还是喜欢这种形式的链接，名称固定，一目了然，而且只要不放出来，别人就不一定能够猜出来）

分页

hexo 的分页依赖于以下插件：
- hexo-generator-index
- hexo-generator-archive
- hexo-generator-tag

默认已在 _config.yml 文件配置了首页的分页

index_generator:
  per_page: 5

同样可以增加相应的分页

archive_generator:
  per_page: 20
  yearly: true
  monthly: true

tag_generator:
  per_page: 10

最后更新： 2021/03/06 00:41:36

作者： David Faraday

主用链接： https://faradays-studio.gitee.io/about/hexo-theme-faradays_summary.html

备用链接： https://faradays-studio.github.io/about/hexo-theme-faradays_summary.html

许可协议： CC BY-NC-SA 4.0.