项目 | 基于 Hexo 框架在 Github 上搭建博客

序言

Hexo $^{[1]}$,一个快速、简洁且高效的博客框架,若以个人博文为主导需求,它的强大毋庸置疑。

Hexo 支持 GitHub Flavored Markdown 的所有功能;且基于 Node.js 所带来的超快生成速度,百页博文秒级渲染;开放性 API 以及丰富的插件等,即功能来得纯粹,不失个性化定制,上手容易且操作便捷。更重要的一点,它是开源的、免费的博客框架,数据保存在本地以及 Github 上,相信在众多博客产品中选择、博弈,相信 Hexo 的表现不会令你失望。

对于 Hexo 的安装、使用教程尽量遵照官方使用文档的流程操作,而本文则将侧重于 Hexo 的优化体验、实用插件等方面的内容分享。

若想了解详情可访问「hexo.io」。

更新

  • 2018.01.22:完成文章初稿;
  • 2018.10.25:纠正有纰漏的地方,并重新排版;

壹 搭建环境

  • Mac OS、Windows 环境下的配置流程和步骤大同小异,而搭建环境的大致流程为:
    • Git 环境配置 ( Windows 平台需要配置 );
    • Node.js 环境配置;
    • Github 账号注册和配置;
    • Hexo 的安装和配置.
  • 考虑到是流程操作类的文章,为简单起见,则我们以 MacOS 和 Windows 版本分别说明情况:

MacOS 版本

配置环境

  • Xcode : Hexo 的编译依赖于 Xcode,故我们得在 Mac 上安装 Xcoce。

    • Xcode 可自行到 Apple App Store 下载、安装。
    • 启动 Xcode 并进入 Preferences -> Download -> Command Line Tools -> Install 安装命令行工具。
  • Node.js : Hexo 是基于 Node.js 开发的,即得配置 Hexo 的运行环境。

    • Node.js:官方下载
    • 本地安装,文件包为 Node-Vx.x.x.pkg
    • 检测是否安装成功,当然返回版本信息即成功安装..

      1
      2
      3
      # 终端下输入命令:  
      node -v
      npm -v
  • Github 账户注册与建立 Repository

    已有账号、项目可忽略此步骤,但注意代码库的配置属性。

    • 注册账号:GitHub 社区注册入口
    • 创建代码库:

      • Step.01. Add ( 右上角「+」图标 ) -> New Repository
      • Step.02. Repository Name,填写 yourname.github.io
      • Step.03. Repository Description,填写简单描述.
    • 配置代码库:

      • Step.01. 进入项目 yourname.github.io
      • Step.02. Settings -> GitHub Pages,开启 GH-Pages 功能;
      • Step.03. 点击 Launch Automatic Page Generator.

        Github 将会自动替你创建出一个 GH-Pages 的页面。若配置没有问题,约15分钟后,yourname.github.io 就可以正常访问了,配置结束。

安装 HEXO

安装 HEXO
  • 本地选择安装目录:

    1
    cd your-hexo-site
  • 在线安装 HEXO ( NPM淘宝源 ):

    1
    2
    3
    npm install hexo-cli -g  
    hexo init
    hexo install
  • 检测是否安装成功,当然返回版本信息即成功安装:

    1
    hexo -v
运作 HEXO
  • 本地运作 HEXO:

    1
    hexo server # 或简写 hexo s
  • 当终端提示以下信息,则本地配置工作基本完成:

    Hexo is running at http://localhost:4000/. Press Ctrl+C to stop.

使用 HEXO

注意:此项操作,需要确保在 Hexo 安装目录下执行。

  • 新建一篇博文 ( 当然,更新过往的文章只需修改 Hexo -> Source -> _Posts 目录下相对应的 MarkDown 文件即可 )

    1
    hexo new post "Article Title"
  • 生成博文 ( 生成静态网页 )

    1
    hexo generate
部署至 GitHub
  • 部署至 Git 的准备工作:

    1
    2
    3
    4
    5
    # 在部署前,还需要安装「Git部署插件」:  
    npm install hexo-deployer-git --save

    # 若没有安装该插件,会出现情况:
    # deloyer not found:git
  • 再者,与 Github 连接前需要获得授权,不然会出现以下情况 ( 本机没有配置 Public Key ):

    Permission denied (publickey).
    fatal: Could not read from remote repository.
    Please make sure you have the correct access rights and the repository exists.

  • 配置 SSH KEY / Public KEY ( RSA 认证 ):

    [注意] 若之前机器上配置了 Git 的信息,请跳过该步骤。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    # 1. 配置 Git 的 UserName 和 Email 
    # “YourAnonymousName",可以替换成自己的用户名
    git config --global user.name "YourAnonymousName"
    # "UserName@xxx.com",替换成自己的邮箱
    git config --global user.email "UserName@xxx.com"

    # 2. 检查是否已经有 SSH KEY
    # Step01. 列出该目录下的文件;
    # Step02. 看是否存在「id_isa」和「id_isa.pub」文件;
    cd ~/.ssh
    ls

    # Step03. 若存在则跳过,没有则执行此步骤「生成密钥」.
    # 邮箱「UserName@xxx.com」替换成自己的邮箱
    ssh-keygen -t rsa -C "UserName@xxx.com"

    # 3. 登陆 Github, 添加 SSH KEY
    # Step01. Avatar(头像) > Settings > Personal Settings > SSH and GPG keys;
    # Step02. New SSH KEY,把「id_isa.pub」的密钥粘贴过去即可.

    # 4. 测试是否配置成功
    ssh -T git@github.com
    # 提示「Hi YourName! You've successfully authenticated, but GitHub does not provide shell. access.」即成功配置。
  • 配置 _config.yml 文件 :

    • 在 Hexo 安装目录下找到 _config.yml 文件,如 ~/你的安装目录/Hexo/_config.yml。找到 deploy 字段,修改配置。

      1
      2
      3
      4
      deploy:  
      type: git
      repo: https://github.com/yourname/yourname.github.io.git
      branch: master
    • 注意: 冒号后面含一个空格;使用 Github 不用 branch 字段;若使用多个 deployer,则有:

      1
      2
      3
      4
      5
      deploy:
      - type: git
      repo:
      - type: heroku
      repo:
  • 部署至 Git:

    1
    2
    hexo deploy	  
    hexo d -g # 即在部署之前先生成

Windows 版本

配置环境

Github 账号注册和配置和 Hexo 的安装和配置,在 Windows 与 MacOS 上是通用的。因此,在 Windows 版本中,主要阐述 Node.Js和 Git 的安装和配置即可。

  • Node.js 的安装和准备:

  • Git 的安装和准备:

    • 下载并安装:Git for Windows x86/x64 bit
    • 检测是否安装成功,当然返回版本信息即成功安装。

      1
      git --version

贰 优化拓展

至此,Hexo 的安装以及 GitHub 的配置工作暂告一段落。能正常运行使用 Hexo 是没问题的,而下面的章节则是对 Hexo 的扩展和个性化定制,根据自己的需求挑选阅读、实践。

套用一款主题

  • Hexo 安装主题的方式非常简单,只需要将主题文件拷贝至站点目录的 themes 目录下, 然后修改下配置文件即可。

  • 在 Hexo 中有 两份 主要的 配置文件,其名称都是 _config.yml。 其中,一份位于 站点根目录 下,主要包含 Hexo 本身的配置;另一份位于 主题目录 下,这份配置由主题作者提供,主要用于配置主题相关的选项。

    为了描述方便,在以下说明中,将前者称为 站点配置文件, 后者称为 主题配置文件。具体以 NexT $^{[2]}$ 为例说明,安装步骤如下。

下载主题

  • 如果你熟悉 Git, 建议你使用 克隆最新版本 的方式,之后的更新可以通过 git pull 来快速更新, 而不用再次下载压缩包替换。

    1
    2
    3
    4
    5
    6
    7
    # 克隆最新版本
    cd your-hexo-site
    git clone https://github.com/iissnan/hexo-theme-next. themes/next

    # 快速更新
    cd themes/next
    git pull

启用主题

  • 与所有 Hexo 主题启用的模式一样。 当 克隆/下载 完成后,打开 站点配置文件, 找到 theme 字段,并将其值更改为 next

    1
    theme: next
  • 到此,NexT 主题安装完成。下一步我们将验证主题是否正确启用。在切换主题之后、验证之前, 我们最好使用 hexo clean 来清除 Hexo 的缓存。

    1
    hexo clean

主题设定

外观设定
  • 选择 Scheme:Scheme 是 NexT 提供的一种特性,借助于 Scheme,NexT 为你提供多种不同的外观。同时,几乎所有的配置都可以在 Scheme 之间共用。目前 NexT 支持三种 Scheme:

    • Muse:默认 Scheme,黑白主调,大量留白。
    • Mist:Muse 的紧凑版本,整洁有序的单栏外观。
    • Pisces:双栏 Scheme,小家碧玉似的清新。

      1
      2
      3
      #scheme: Muse
      #scheme: Mist
      scheme: Pisces

      Scheme 的切换通过更改 主题配置文件,搜索 scheme 关键字。 你会看到有三行 scheme 的配置,将你需用启用的 scheme 前面注释 # 去除即可。

设置语言
  • 设置语言:编辑站点配置文件, 将 language 设置成你所需要的语言,例如 language: zh-Hans。建议明确设置你所需要的语言,例如选用简体中文,配置如下 ( 更多请语言配置请参考下述表格 ):
语言 代码 设定示例
English en language: en
简体中文 zh-Hans language: zh-Hans
Français fr-FR language: fr-FR
Português pt language: pt or pt-BR
繁體中文 zh-hk language: zh-hk
Русский язык ru language: ru
Deutsch de language: de
日本語 ja language: ja
Indonesian id language: id
Korean ko language: ko
设置菜单
  • 菜单配置包括三个部分,第一是菜单项 ( 名称和链接 ),第二是菜单项的 显示文本,第三是菜单项对应的 图标

  • NexT 使用的是 Font Awesome $^{[3]}$ 提供的图标,600+ 的图标可满足大部分需求,且适配 Retina 屏幕。

  • 编辑 主题配置文件,修改以下内容:

    请注意键值( 如 home )的大小写要严格匹配。

    • 设定菜单内容,对应的字段是 menu,菜单内容的设置格式是:item name: link。其中 item name 是一个名称,这个名称并不直接显示在页面上,她将用于匹配图标以及翻译。

      1
      2
      3
      4
      5
      6
      7
      8
      9
      menu:
      home: /
      archives: /archives
      #about: /about
      #categories: /categories
      tags: /tags
      #commonweal: /404.html

      # 若你的站点运行在子目录中,请将链接前缀的/去掉
    • NexT 默认的菜单项有 ( 标注 * 的项表示需要手动创建这个页面 ):

键值 设定值 显示文本(简体中文)
home home: / 主页
archives archives: /archives 归档页
categories categories: /categories 分类页 *
tags tags: /tags 标签页 *
about about: /about 关于页面 *
commonweal commonweal: /404.html 公益 404 *
  • 设置菜单项的显示文本,在第一步中设置的菜单的名称并不直接用于界面上的展示。Hexo 在生成的时候将使用这个名称查找对应的语言翻译,并提取显示文本。

    这些翻译文本放置在 NexT 主题目录下的 languages/{language}.yml ( {language} 为你所使用的语言 )。以简体中文为例,若你需要添加一个菜单项,比如 something。那么就需要修改简体中文对应的翻译文件languages/zh-Hans.yml,在menu字段下添加一项:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    menu:
    home: 首页
    archives: 归档
    categories: 分类
    tags: 标签
    about: 关于
    search: 搜索
    commonweal: 404
    something: 有料
  • 设定菜单项的图标,对应的字段是 menu_icons

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    menu_icons:
    enable: true
    # Icon Mapping.
    home: home
    about: user
    categories: th
    tags: tags
    archives: archive
    commonweal: heartbeat

    # 此设定格式是「item name: icon name」
    # 「item name」与上一步所配置的菜单名字对应
    # 「icon name」是 Font Awesome 图标的名字
    # 「enable」用于控制是否显示图标,你可以设置成「false」来去掉图标

设置侧栏

  • 可以通过修改 主题配置文件 中的 sidebar 字段来控制侧栏的行为。侧栏的设置包括两个部分,其一是 侧栏的位置, 其二是 侧栏显示的时机

  • 设置侧栏的位置,修改 sidebar.position 的值,支持的选项有:

    left - 靠左放置
    right - 靠右放置

    目前仅 Pisces Scheme 支持 position 配置。影响版本 5.0.0 及更低版本。

    1
    2
    sidebar:  
    position: left
  • 设置侧栏显示的时机,修改 sidebar.display 的值,支持的选项有:

    post - 默认行为,在文章页面( 拥有目录列表 )时显示
    always - 在所有页面中都显示
    hide - 在所有页面中都隐藏( 可以手动展开 )
    remove - 完全移除

    1
    2
    sidebar:
    display: post

    已知侧栏在 use motion: false 的情况下不会展示。影响版本 5.0.0 及更低版本。

设置头像

  • 编辑 主题配置文件, 修改字段 avatar,值设置成头像的链接地址。其中,头像的链接地址可以是:

    • 站外链接:avatar: http://example.com/avatar.png
    • 站内资源:放置在 source/images/ 目录下,images 为自建目录,字段配置为 avatar: /images/avatar.png

揽收实用插件

叁 参考资料

[1] HexoJs. 使用文档. 2018
[2] NexT. 使用文档. 2018
[3] Dave Gandy. Font Awesome Accessibility
[4] 徐俊. 手把手教你搭建属于自己的博客. CSDN. 2017