Hexo部署和使用指北(Windows)

静态博客对比

安装 Step by Step

安装Git客户端node.js环境, 然后你还要有一个Github帐号.
安装完node.js之后, 不要忘记把User/AppData/Roaming/npm添加到PATH.

  • 安装hexo: 打开Git CMD(因为),输入: npm install -g hexo-cli
  • 初始化hexo: hexo init BLOG, 将在当前目录建立”BLOG”为名的目录并在此初始化, Hexo 即会自动在目标文件夹建立网站所需要的所有文件.
  • 安装依赖包: cd BLOG && npm install,
    • 如果需要把Blog部署到Github上, 还需要安装hexo-git模块: npm install hexo-deployer-git --save (这一步可选);
    • 如果需要Blog主页不显示全文而是摘要, 需要安装npm install --save hexo-excerpt (这一步可选);
  • 本地启动测试: hexo server, 然后访问127.0.0.1:4000查看.
  • Github上新建一个repository, 名字为yoursite.github.io
  • 修改本地的_config.yml文件, 找到#site一栏, 修改博客的title, 然后在最后的deploy:处增加下面几行:

    type: github
    repository: https://github.com/Your_Github_Account/yoursite.github.io.git
    branch: master
  • 添加评论系统: 国外比较常用的评论系统有disqus等, 这个在hexo中也是默认开启的, 如果我们要添加其他的评论系统, 还需要做一点修改.
    在国内推荐使用搜狐畅言: 搜狐畅言-专业的社会化评论系统.
    首先需要在配置文件中禁用disqus, 编辑根目录的_config.yml文件: 查找并注释掉disqus_shortname一行.
    然后编辑 themes\landscape\layout\_partial\article.ejs文件, 在文件最后找到section id="comments"一段, 修改为:

    <% if (!index){ %>
    <section id="comments">
    <%- partial('comment') %>
    </section>
    <% } %>

    编辑themes\landscape\layout\_partial\comment.ejs 并添加畅言的Js代码:

附: hexo命令列表

hexo new "post title with whitespace"
hexo new page --path about/me "About me"
hexo generate
hexo server
hexo deploy
hexo clean: 清除缓存文件 (`db.json`) 和已生成的静态文件 (`public`)
hexo version

附: npm命令列表

npm ls
npm outdated
npm update # npm update [-g] [<pkg>...]
npm install [-g] moduleName [--save] # -g 全局安装 , --save将被写入package.json的dependencies
npm uninstall [<pkg>...]
npm cache clean

使用NexT主题

下载NexT主题:

cd BLOG
git clone https://github.com/iissnan/hexo-theme-next themes/next

修改_config.yml:

theme: next

如果使用了NexT主题, 第三方评论系统需要在themes/nextlayout/_partials/comments.swig修改, 增加畅言评论的js

添加/修改文章

  1. 打开Git Bash并执行:
    • hexo n 文章名 新建文章, 这将在hexo\source_posts\目录下新建同名的Markdown文件, 用你喜欢的markdown编辑器写博客…
    • hexo g : 这将在hexo.deploy目录下生成静态页面.
    • hexo d : 把文章推到到Github上.
  2. 部署完成后, 访问yoursite.github.io就能看到自己搭建的博客了.

注意, Hexo解析某些含有 {#, {%的代码块会有问题, 在执行hexo g的时候会抛错, 折中解决办法就是..用全角字符😁

Front-matter

Hexo 的 YAML Front-matter 支持的属性:

title:	标题	文章的文件名
date: 建立日期 文件建立日期
updated: 更新日期 文件更新日期
comments: 开启文章的评论功能 true
tags: 标签(不适用于分页)
categories: 分类(不适用于分页)
permalink: 覆盖文章网址
excerpt: Page excerpt in plain text. Use this plugin to format the text

为Hexo增加更多特性…

SEO推广

生成sitemap

Sitemap用于通知搜索引擎网站上有哪些可供抓取的网页,以便搜索引擎可以更加智能地抓取网站。

  • 安装插件hexo-generator-sitemap,用于生成sitemap:npm install hexo-generator-sitemap --save
  • 站点配置文件 _config.yml中添加如下字段:
    sitemap:
    path: sitemap.xml

如果post标题中有& >等符号,可能会导致sitemap生成有问题,浏览器打开后可看到 “xmlParseEntityRef: no name”的错误提示

添加 robots.txt

网站通过Robots协议告诉搜索引擎哪些页面可以抓取,哪些页面不能抓取。robots.txt 通常存放于网站根目录。
在source文件夹下新建robots.txt文件,文件内容如下:

User-agent: *
Allow: /
Allow: /archives/
Allow: /categories/
Allow: /tags/
Disallow: /vendors/
Disallow: /js/
Disallow: /lib/
Disallow: /css/
Disallow: /fonts/
Sitemap: https://your_site.com/sitemap.xml

Hexo正文中标题自动编号

  • 安装heading-index: npm install hexo-heading-index --save
  • 修改顶层_config.yml

    heading_index:
    enable: true
    index_styles: "{1} {1} {1} {1} {1} {1}"
    connector: "."
    global_prefix: ""
    global_suffix: ": "
  • 修改Hexo主题下的_config.yml, 避免侧边栏重复自动生成编号,禁用侧边栏自动编号

    toc:
    enable: true
    # Automatically add list number to toc.
    number: false

Hexo处理锚点的问题

Markdown文章里的锚点,
如果是本文内的锚点, 可以用[锚点名称](#章节),
如果是章节外的锚点, 可以用https://URI/#章节

但是需要注意的是:

  • 如果标题里带标点符号, 大多数情况下(比如常用的Hexo, Github, Gitlab的解析器)Markdown解析成html锚点后都会把标题里的英文标点符号转换成-, 但中文标题里的标点不会被转换.
  • 英文字母要全部小写.

比如本文中的### 添加 robots.txt标题, 转成html后锚点变成添加-robots-txt:

https://whatsrtos.github.io/blog_archive/Hexo部署和使用指北/#添加-robots-txt

NexT 主题修改Toc

NexT主题的Toc列表是在sidebar显示的, 如果在手机或平板等小屏幕设备上不显示sidebar,
如何在手机浏览时可以显示sidebar的Toc可以参考:
Next主题小屏幕下保留侧边栏 | J.F’s BLOG

NexT 主题自定义css

NexT的自定义文件在: source/css/_custom/custom.styl

NexT 主题支持数学公式

安装:

npm install hexo-math --save

在站点配置文件 _config.yml 中添加:

math:
engine: 'mathjax' # or 'katex'
mathjax:
# src: custom_mathjax_source
config:
# MathJax config

在 next 主题配置文件中 themes/next-theme/_config.yml 添加:

# MathJax Support
mathjax:
enable: true
per_page: false
cdn: //cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML

使用:

行内公式: $数学公式$
行间公式, 独占一行: $$数学公式$$

自定义post排序

主页的post 默认是按创建时间排序,主页文章排序在配置文件:

index_generator:
path: ''
per_page: 0
order_by: -date

order_by 可以是 yaml front matter里定义的属性(没测试)

但是 category 页面的 post 排序没有可配置选项,需要直接改代码 node_modules/hexo-generator-category/lib/generator.js

var posts = category.posts.sort('title');  // 按 yaml front matter 里的title排序

插件列表

  • [x] hexo-generator-index-pin-top: 增加文章置顶功能, 在文章 front-matter 里增加top: True即可
  • [ ] hexo-heading-index : 为标题(headings)添加自动编号
  • [x] hexo-generator-sitemap: 生成sitemap
  • [x] hexo-excerpt: 主页显示文章摘要而不是全文
  • [ ] hexo-toc: 将markdown代码中的 <!-- toc --> 替换为TOC(Table Of Content) // 已知的问题: 会导致NexT的边栏TOC不可用
  • [x] hexo-math: mathjax 数学公式渲染
  • [x] hexo-backlink: 将obsidian的双链[[转换为 mkd 链接,但是不支持相对路径

问题修复

node版本导致hexo g生成静态文件size=0

降级node:

brew uninstall node
brew install node@12
brew link --overwrite --force node@12

参考:

hexo-renderer-marked版本导致图片解析问题

发现有些博文里的markdown图片没有正常解析, 看起来像是render的问题, 因为最近重新安装过hexo-renderer-marked,
我的Hexo还是3.5版本, 在hexo-renderer-marked的github页面看到 0.2+版本适用于Hexo 3,
用npm list 查看目前安装的hexo-renderer-marked版本, 已经是2.0.0了,
所以试试降低hexo-renderer-marked的版本.

使用npm view hexo-renderer-marked versions命令查看所有已发布版本, 然后使用npm install hexo-renderer-marked@0.2.11 --save安装0.2版本的.
ps: hexo-renderer-ejs, hexo-renderer-stylus 也需要降级

npm view hexo-renderer-stylus  versions

npm uninstall hexo-renderer-marked && npm uninstall hexo-renderer-ejs && npm uninstall hexo-renderer-stylus

npm install hexo-renderer-marked@0.2.11 --save && npm install hexo-renderer-stylus@0.2.3 --save && npm install hexo-renderer-ejs@0.2.0 --save

参考: