Hexo 使用指南

记录使用hexo中碰到的一些坑,以及一些常用的东西.

[TOC]

1. 快速使用

1.1 基本了解

Node.js与hexo的关系:  
Node.js是一门语言，hexo是一个建立网站的库.   
安装好Node.js后，前面本地之前使用过的网站文件夹，里面实际上已经有hexo了，不需要重新安装.  
npm是Node.js安装各种库（包括hexo，以及hexo的子库）的命令，相当于python里面的pip.  

git是上传到github的工具,上传到GitHub，需要配置ssh key，一机一码，并复制给github

1.2 安装Hexo

1.下载按照Node.js和Git
http://nodejs.org/
http://git-scm.com/

2.Git Bash下安装Hexo（Homepage这个文件夹其实里面已经安装了一个，这步可以跳过）
npm install -g hexo-cli

3.在Homepage下，Git Bash命令

打开服务：hexo s
生成静态网页：hexo g
清楚静态网页：hexo clean
上传：hexo d
创建新文章：hexo new post —path pytorch/123

1.3 配置github

1.ssh key配置

就是本地和远程仓库之间的暗号,本地生成一个暗号,告诉远程仓库,以后使用git推送文件到

远程仓库时,会自动核对暗号,暗号正确,那么就可以推送成功,不需要核对账号密码这么麻烦了

如果换电脑，需要重新配置ssh key,或者你备份一下复制到新电脑里（需要用户名和邮箱设置和之前一样）
https://www.bbsmax.com/A/kvJ3Z8KAzg/
一般ssh key所在目录为
C:\Users\Administrator.ssh
文件名为 id_rsa.pub

当然,除了配置git的密钥,还需要配置本地user信息,就是user的用户名的邮箱,可以瞎填,这个就是一个身份代号,

远程仓库的人好知道是张三推过来的代码还是李四推过来的.配置教程直接网上搜,非常简单.

至此,git的配置工作就完成了.

2.hexo单独配置一键推送的插件
安装好git后，在hexo里面安装一键上传插件
hexo-deployer-git
安装好后，打开_config.yml进行配置
配置教程：https://hexo.io/zh-cn/docs/one-command-deployment
教程下面还有一堆使用git之外的工具进行上传的，没有使用git配合hexo插件方便

3.配置端口和代理

配置代理是因为有时候github无法访问，配置系统代理，与设置—网络—代理中的系统代理一致，需要

你用软件打开系统代理，在系统设置的网络的代理中才能看到

代理配置：git设置、查看、取消代理_git 取消代理-CSDN博客

如果上传的时候出现下方错误，说明你的22号端口被学校或者机构禁用了，需要换端口

ssh: connect to host github.com port 22: Connection timed out
fatal: Could not read from remote repository.

端口配置：坑：ssh: connect to host github.com port 22: Connection refused - 知乎 (zhihu.com)

2. hexo文件夹介绍

2.1 _config.yml文件

网站的配置信息，可以在此配置大部分的参数,一些插件安装后,相关配置有时也在这里进行

2.2 source文件夹

资源文件夹，存放用户资源的地方（放图片、Markdown文档、文章、草稿、各种页面等）

source/__posts ：存放文章的markdown源文件，会被编译成 html 文件
source/categories: 分类文件夹，文章有categories参数的话，会把文章添加到此目录
source/tags: 标签文件夹，同上.

当上传到github后,source作为资源根目录,比如/img就表示source/img

2.3 scaffolds文件夹

模版文件夹，是指在新建的文章文件中默认填充的内容，如果文章需要分类，可以加个categories参数，以后每次新建post时候，文章头都会添加这个参数

2.4 public文件夹

生成的静态网页文件，用于上传到GitHub，这个文件夹就是你看到的页面，其文件目录就是真正的路径地址

2.5 package.json文件和node_module文件夹

package.json：查看Hexo的版本以及相关依赖包的版本

node_module文件夹：所有的包

​ Hexo会默认安装：

​ hexo：主程序
​ hexo-deployer-git：实现git部署(在_config.yml中配置参数后可以一键部署)
​ hexo-generator-archive：存档页面生成器
​ hexo-generator-category：分类页面生成器
​ hexo-generator-index：index生成器（可以删除，用index2插件代替，以实现文章排序）
​ hexo-generator-tag：标签页面生成器
​ hexo-renderer-ejs：支持EJS渲染
​ hexo-renderer-marked：Markdown引擎
​ hexo-renderer-stylus：支持stylus渲染，主题需要
​ hexo-server：支持本地预览，默认地址localhost:4000

插件使用核心

插件安装在node_module目录下，启用插件以及插件的配置参数，在_config.yml文件中填写，

一般插件源代码中的变量名前面都有个config前缀，就是从config中读取变量

​

2.6 themes/jelly/layout 和 themes/jelly/source/css

相应主题（这里是jelly）的页面排版布局，比如字体，图标的源文件和设置一般在css中，而

页面的其他布局一般在layout中

    ##### example

​ 比如打开layout/_partial下的left-col.ejs文件，会有这么一行代码

<nav class="header-menu">
    <ul>
    <% for (var i in theme.menu){ %>
        <li><a href="<%- url_for(theme.menu[i]) %>"><%= i %></a></li>
    <%}%>
    </ul>
</nav>

在主题_config.yml中menu下，加入一项nndl案例与实践后，通过上述for遍历得到变量名theme.menu，从而把”nndl案例与实践”加入menu当中

而配置menu字体大小写的文件，在主题文件夹的source/css/_partial的main.styl文件中，只需要修改text-transform属性即可

3. 如何正确引用相对路径

3.1 _config.yml配置

参数	描述	默认值
source_dir	资源文件夹，这个文件夹用来存放内容。	source
tag_dir	标签文件夹	tags
archive_dir	归档文件夹	archives
category_dir	分类文件夹	categories
skip_render	跳过指定文件的渲染,文件将会被不做改动地复制到 public 目录中

3.2 引用说明

• 比如插入一张图片，路径格式应为

​ /img/figure.png

​ 那么会引用source/img/figure.png

实际上source下面创建的资源文件夹在生成静态网页时会跑到根目录下，因此引用路径为/img

• tips：

  本地写文章时，在md所在文件夹下先建立img文件夹，放好图片，然后复制到source文件夹下

• 比如menu中引用categories中的nndl

​ /categories/nndl

​ 那么会引用source/categories/nndl

4. 如何在文章中插入pdf在线预览

step1：

​ 到hexo网站文件夹下安装

​ npm install hexo-pdf —save

step2：

​ 在文章需要加入pdf的地方

{% pdf /pdf/xxx.pdf %}

​ 其中，xxx.pdf放在source的pdf文件夹下

​ 注：本地打开网页，会跳出保存pdf，上传到服务器后，才是预览

step3：

​ 到node_modules/hexo-pdf下打开reader.ejs

​ 将height=”550”改为height=”800”

​ 这样预览pdf的窗口高度就会变高

5. 如何修改头像，logo

头像

​ 一般在主题的_config.yml中可以直接配置，头像文件一般在source/img文件夹下

小部件的logo

​ 这个可能在主题source/css/fonts文件夹下的字体文件fontawesome中

6. 关于menu导航栏的文章分类定制

在主题的_config.yml中设置如下

menu:
 主页:  2022/08/09/home/me/
 #全部文章: /
 文章归档: /archives
 nndl案例与实践: /categories/nndl

• 第一项

  主页: 2022/08/09/home/me/

  首先新建个人简介文章，然后生成静态网页或者本地打开这篇文章，查看这篇文章的路径

  然后把这个路径复制过来，这样打开主页按钮，就会显示整篇文章

• 第二项

  全部文章：/

  显示所有文章，由于文章太多，这里不建议使用此项

• 第三项

  文章归档，按日期给文章分类

• 第四项

  自定义栏目，一般显示的文件夹为categories的子文件夹，这样给文章加个分类标签容易管理

  创建分类文件夹代码如下：

  hexo new post --path analysis/123

  新目录名称为analysis，里面默认创建一个123.md文件

7. 文章分类与排序：hexo-generator插件介绍

hexo-generator-index 用于生成主页

hexo-generator-category 用于生成目录页

hexo-generator-archive 用于生成文章归档页

上面三个插件都是通过调用hexo-pagination函数生成页面

7.1 pagination函数的返回值

{
      path: xxxDir,     // 路径
      layout: ['layout1', 'layout2', 'layout3', 'layout4'],  //指定布局，首先找有没有1模板 没有依次往下找
      data: {
        base: xxxDir,
        total: 1,
        current: 1,
        current_url: tagDir,
        posts: locals.posts,
        prev: 0,
        prev_link: '',
        next: 0,
        next_link: '',
        tags: tags
      }

7.2 主题_config.yml的menu配置（生成各种导航按钮）

menu:
  主页:  2022/08/09/home/me/
  笔记: /categories/notes
  nndl案例与实践: /categories/nndl

7.3 根目录_config.yml配置

# index 页面配置
index_generator:
  path: ''
  per_page: 15
  order_by: top

# Category 页面配置
category_generator:
  layout: index
  per_page: 15
  order_by: top
  
# Archive 页面配置
archive_generator:
  layout: index
  per_page: 15
  order_by: top
  
# Tag 页面配置
tag_generator:
  layout: index
  per_page: 15
  order_by: top

• path: 文章源路径
• per_page: 每页显示的文章数量

• order_by: -date表示按日期降序，top表示按top值升序

• 置顶的字样如果不想要，可以在主题的layout/_partial/post下的title.ejs中修改

7.4 生成页面布局修改

比如想要把category页面布局生成的和主页布局一样，直接找到插件目录下的lib/generator.js，修改

layout: ['index','category', 'archive']

默认就会选择index布局

7.5 布局目录

主题文件夹下的layout文件夹

8. 数学公式支持

8.1 插件依赖

安装：

hexo-renderer-mathjax

hexo-renderer-kramed 或者 hexo-renderer-pandoc

卸载：

hexo-renderer-marked

hexo-math

8.2 主题config.yml配置

math:
  # Default (true) will load mathjax / katex script on demand.
  # That is it only render those page which has `mathjax: true` in Front-matter.
  # If you set it to false, it will load mathjax / katex srcipt EVERY PAGE.
  per_page: true

  # hexo-renderer-pandoc (or hexo-renderer-kramed) required for full MathJax support.
  mathjax:
    enable: true
    # See: https://mhchem.github.io/MathJax-mhchem/
    mhchem: false

8.3 文章头设置

mathjax: true

8.4 更改 hexo-renderer-kramed 部分转义规则

主要是因为hexo-renderer-kramed渲染MathJax时与Markdown语法冲突

找到

node_modules\kramed\lib\rules\inline.js

修改以下几个地方：

问题描述：当公式中出现\\表示换行时，会被kramed渲染为\，导致公式显示异常。

解决：修改第 11 行的 escape 变量的值，这一步是在原基础上取消了对 \ , { , } 的转义

把 escape: /^\\([\\`*{}\[\]()#$+\-.!_>])/,
改为 escape: /^\\([`*\[\]()#$+\-.!_>])/,

问题描述：当公式中出现多个下划线时，会被kramed渲染为Markdown斜体，导致公式显示异常。

解决：修改第 20 行的 em 变量的值，这一步取消了对斜体标记_的转义

把 em: /^\b_((?:__|[\s\S])+?)_\b|^\*((?:\*\*|[\s\S])+?)\*(?!\*)/,
改为 em: /^\*((?:\*\*|[\s\S])+?)\*(?!\*)/,

其他渲染冲突问题

8.5 本地渲染成功，部署到github远程端不能渲染数学公式

参考

先说原因，简单来说就是本地的mathjax脚本可以启用成功，发布到远程的时候，别人打开网页，网页会自动使用mathjax官网服务器的脚本来渲染公式，假如调用脚本失败，那么网页公式就会渲染失败。而调用失败的原因就是网页安全限制了调用脚本，解决方法就是更改mathjax的cdn或者到GitHub上取消https

定位到

\node_modules\hexo-renderer-mathjax\mathjax.html

把原来的

<script src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

修改为

<script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

9. 导航栏设置

9.1 主题config.yml配置

仿照menu的格式，可以创建一个submenu，名字随意，这个主要用来存取子菜单的变量名和链接的

9.2 主题布局文件layout/_partial/left-col.ejs添加代码

<nav class="header-menu">
	<ul>
	<li><a style="color:rgb(228, 117, 238)">Deep Learning </a>
		<nav class="header-submenu">
			<ul>
				<% for (var i in theme.DeepLearning) { %>
					<li><a href="<%- url_for(theme.DeepLearning[i]) %>"><div><%= i %></div></a></li>  
				<% } %>
			</ul>
		</nav>	
	</li>     
	</ul>
</nav>

其中，下面的代码是指定输出的样式为header-menu，这个样式文件在主题/source/css/_partial/main.styl中可以找到

<nav class="header-menu">
</nav>

然后，下面的代码，是输出字体 Deep Learning，并且不带链接的纯字体，并且可以修改颜色

<li><a style="color:rgb(228, 117, 238)">Deep Learning </a>
</li>

然后，下面的代码是指定输出的样式为header-submenu，同样也在main.styl中，只不过这个样式是我们增加的，需要拷贝前面的导航menu的样式，然后稍作修改，变成子菜单的样式

<nav class="header-submenu">
			<ul>
				<% for (var i in theme.DeepLearning) { %>
					<li><a href="<%- url_for(theme.DeepLearning[i]) %>"><div><%= i %></div></a></li>  
				<% } %>
			</ul>
		</nav>	

需要注意的是，我们的分类目录就按照一级目录，不作任何改变

10. 如何添加评论

10.1 可用评论插件：

gitalk，vline等，注意，这些插件一般两种使用方法，第一种就是安装到本地，把css，js文件弄到相应文件夹，然后就可以创建相应的容器，也就是评论框了，第二种方法是在线引入样式文件，然后在需要的位置引入容器，由此可知，容器是依赖样式文件的；

10.2 gitalk的基本配置：

第一点，你就按网上申请那个OAuth Apps，这个主要是用来把评论的数据存到你github仓库的issues里面的，方便管理；

第二点，你先按网上的方法进行设置，看看能不能成功，其实就是在layout/_partial文件夹下配置引入cdn和显示容器的JavaScript文件，名称一般设置为gitalk.ejs，然后在layout文件夹下的article.ejs文件夹内使用插入代码，把刚刚设定好的代码插进你需要的位置。其实两步可以一步搞定，直接把那串代码复制到相应的位置就行了。另外gitalk.ejs里面多次引用了主题config.yml中预设好的变量，这步可以直接填写变量，省去主题文件的配置了。

第三点，假如这个方法无法正常显示，我就是这样，排除其他原因，我这里最后是引入cdn的问题，也就是那把引入cdn的代码放在需要插入评论的位置，就不行，而是需要插入到这个html文件的开头，找到layout文件夹下的head.ejs(跟article.ejs一个文件夹)，然后在

<%- js('//cdn.bootcss.com/require.js/2.3.2/require.min.js') %>
<%- js('//cdn.bootcss.com/jquery/3.1.1/jquery.min.js') %>

这两句代码之前，插入

<link rel="stylesheet" href="https://unpkg.com/gitalk/dist/gitalk.css">
<%- js('https://unpkg.com/gitalk/dist/gitalk.min.js') %>
<%- js('https://priesttomb.github.io/js/md5.min.js') %>

注意，<%js('https://unpkg.com/gitalk/dist/gitalk.min.js') %> ,会被编译成

<script src="https://unpkg.com/gitalk/dist/gitalk.min.js"></script>

而在article.ejs的最后，添加如下代码，就能添加评论的容器，实例化，并渲染

<% if (!index && post.comments){ %>
    <section id="comments" style="margin: 60px;">
      <div id="gitalk-container"></div>
      <script>
      var gitalk = new Gitalk({
          clientID: #按网上教程改,
          clientSecret: #按网上教程改,
          repo: #按网上教程改,
          owner: #按网上教程改,
          admin: [#按网上教程改],
          id: md5(location.pathname),      // Ensure uniqueness and length less than 50
          distractionFreeMode: false  // Facebook-like distraction free mode
        })
      gitalk.render('gitalk-container')
      </script>
      
    </section>
<% } %>

第四点，github上需要在issues上面新建一个标签，名称为gitalk