利用GitHub Pages搭建Hexo静态博客教程

2,025 阅读12分钟

利用GitHub Pages搭建Hexo静态博客教程

Written By Tomy Stark.
E-mail: ro7enkranz@qq.com

原文链接:apex.linn.top/2019-09-28-…

Note: 转载请注明本文出处链接、作者

什么是 Hexo

Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 Markdown(或其他渲染引擎)解析文章,在几秒内,即可利用靓丽的主题生成静态网页。

搭建 Hexo 博客需要什么

  • Visual Studio Code(用于作为 Markdown 编辑器,由于内部集成了终端,非常方便,必备!)
  • Node.js(Node.js 版本需不低于 8.6,建议使用 Node.js 10.0 及以上版本)
  • Git(用于将编译好的 Hexo 静态博客文件部署到 GitHub Pages)
  • GitHub 帐号(帐号注册请自行完成,注册流程本文不做叙述)

详细步骤

1. 安装必要软件

  • Visual Studio Code

    下载完成后安装即可,没有特别需要注意的地方(安装目录可自己手动指定

    建议安装完成后,在 VS Code 中安装以下扩展插件:

    • Chinese (Simplified) Language Pack for VS Code
    • changeEncode
    • GBKtoUTF8
    • markdownlint
    • Markdown All in One
  • Node.js

    按照默认设置一直 Next 安装即可(安装目录可自己手动指定

  • Git

    注意其中一步选择 VS Code 作为 Git 的默认编辑器,其它默认(安装目录可自己手动指定

选择VS Code作为Git的默认编辑器

2. 注册 GitHub 帐号

  • 注册链接:GitHub 帐号注册(帐号注册请自行完成,注册流程本文不做叙述)

    注意:请在注册完成后验证邮箱

3. 在 GitHub 上新建仓库

  • 登录账号后,页面右上角 + 号,选择 New repository

New repository

  • 如果你希望你的站点能通过 <你的 GitHub 用户名>.github.io 域名访问,你的 repository 应该直接命名为 <你的 GitHub 用户名>.github.io。例如,我的用户名为 SummerFalls,那么该仓库名就应该为 SummerFalls.github.io,详见下图:

新建 GitHub 仓库

  • 新建完成后出现如下图页面:

仓库新建完毕

4. 安装 Hexo

  • 打开 VS Code,按下 Ctrl + ` 打开内部集成的终端
  • 先测试 Node.js 是否被能够被 VS Code 的终端所调用
    • VS Code 的终端中输入命令 npm -v
      • 如果正常,则会显示其版本号,例如 6.9.0
      • 如果异常,则会提示类似错误:npm : 无法将“npm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写,如果包括路径,请确保路径正确, 然后再试一次。这时,请关闭 VS Code,然后将其设置为 以管理员身份运行此程序,之后重新运行 VS Code,如图所示:

设置 VS Code 管理员权限

  • 定位到你想用于存放博客源文件夹的目录,我这里以C盘根目录为例

    cd C:\

  • 执行 npm 命令进行全局安装 Hexo

    npm install hexo-cli -g

  • 初始化 Hexo 博客(此举会在当前目录创建名为 blog 的文件夹)

    hexo init blog

  • 进入 blog 文件夹

    cd blog

  • 通过 blog 目录下的 package.json 进一步安装依赖,之后会产生一个 node_modules 文件夹

    npm install

  • 启动 Hexo 本地服务器

    hexo s

  • 检查 Hexo 是否安装成功,在执行上面的命令之后,终端会返回如下信息,按住 Ctrl + 鼠标左键单击 该链接即可打开

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

  • 打开后的页面如图,即说明 Hexo 安装成功

Hexo 初始页面

  • 回到 VS Code,切换到终端,按下 Ctrl + C,之后输入 Y 以停止 Hexo 服务器

5. 配置 Hexo

  • VS Code 中按下快捷键 Ctrl + K + O,打开你的博客源文件夹,如图:

打开博客源文件夹

  • 打开左侧 侧边栏 中的 _config.yml 文件进行修改,如下所示,请认真阅读注释说明

    # Hexo Configuration
    ## Docs: https://hexo.io/docs/configuration.html
    ## Source: https://github.com/hexojs/hexo/
    
    # Site
    title: Tomy Stark's Blog                # 你的博客名
    subtitle: 四海茫茫                       # 子标题
    description: STM32, TI C2000, S32K      # 博客描述,SEO相关
    keywords: C, C++                        # 关键词
    author: Tomy                            # 博主名字
    language: zh-CN                         # 语言,**关系到主题所显示的语言**
    timezone:                               # 时区,默认留空
    
    # URL
    ## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
    url: 'https://SummerFalls.github.io' # 域名设置,如果没有自己的域名,则地址应为 https://<你的 GitHub 用户名>.github.io 例如我的为: https://SummerFalls.github.io
    root: /
    permalink: :year-:month-:day-:title.html # 建议将永久链接改成如此
    permalink_defaults:
    
    # Directory
    source_dir: source
    public_dir: public
    tag_dir: tags
    archive_dir: archives
    category_dir: categories
    code_dir: downloads/code
    i18n_dir: :lang
    skip_render:
    
    # Writing
    new_post_name: :title.md # File name of new posts
    default_layout: post
    titlecase: false # Transform title into titlecase
    external_link: true # Open external links in new tab
    filename_case: 0
    render_drafts: false
    post_asset_folder: false
    relative_link: false
    future: true
    highlight:
    enable: true
    line_number: true
    auto_detect: false
    tab_replace:
    
    # Home page setting
    # path: Root path for your blogs index page. (default = '')
    # per_page: Posts displayed per page. (0 = disable pagination)
    # order_by: Posts order. (Order by date descending by default)
    index_generator:
    path: ''
    per_page: 5                         # 设置主页中每页显示几篇文章
    order_by: -date
    
    # Category & Tag
    default_category: uncategorized
    category_map:
    tag_map:
    
    # Date / Time format
    ## Hexo uses Moment.js to parse and display date
    ## You can customize the date format as defined in
    ## http://momentjs.com/docs/#/displaying/format/
    date_format: YYYY-MM-DD
    time_format: HH:mm:ss
    
    # Pagination
    ## Set per_page to 0 to disable pagination
    per_page: 10                        # 设置归档(archives)页面每页显示文章数
    pagination_dir: page
    
    # Extensions
    ## Plugins: https://hexo.io/plugins/
    ## Themes: https://hexo.io/themes/
    theme: landscape                    # 设置所用的主题,默认为 landscape
    
    # Deployment
    ## Docs: https://hexo.io/docs/deployment.html
    ## repository 之后的链接应为你之前创建的仓库的链接,后面跟上 .git 后缀,如下图,可直接复制仓库链接
    ## 类型为 git
    ## 分支为 master
    deploy:
    type: git
    repository: https://github.com/SummerFalls/SummerFalls.github.io.git
    branch: master
    

复制 repository 链接地址

6. 安装 Hexo 的必备扩展

  • 安装热更新支持包

    npm install hexo-browsersync --save

  • 安装 Hexo Git 支持包,以支持部署 Hexo 博客到 GitHub

    npm install hexo-deployer-git --save

  • 安装网站地图生成支持包(根目录生成 sitemap.xml 方便搜索引擎抓取)

    npm install hexo-generator-sitemap --save

7. 部署 Hexo 博客到 GitHub

  • 生成 Hexo 静态博客网页文件

    hexo g

  • 部署 Hexo 博客到 GitHub

    hexo d

    • 第一次执行本命令会弹出登录框,请登录你的 GitHub 帐号 如图所示:

登录 GitHub 帐号

  • 稍等片刻,待终端命令执行结束后,浏览器打开你的博客网页地址,如图:

    注意这一次网页地址为 _config.yml 文件中 url: 字段后跟随的网页地址(实际上就是你的 GitHub Pages 仓库名),在这里,我的地址就应该为:SummerFalls.github.io

部署后的博客

8. [可选] 设置 Hexo 博客域名解析

I. 设置域名解析

在设置自定义域名之前,请自行在域名服务商购买域名

这里以在阿里云购买的万网域名为例

  • 打开并登录 阿里云
  • 点击网页右上角的控制台
  • 找到 云解析 DNS,如图所示:

云解析 DNS

  • 点击自己购买的域名,进入 解析设置 页面
  • 点击 添加记录 按钮,设置如图所示:
    • 记录类型:CNAME
    • 主机记录:apex

      这里你可以改为自己喜欢的名称

    • 解析线路:默认
    • 记录值:summerfalls.github.io

      记录值改为你的 GitHub Pages 仓库名称

    • TTL:10分钟

解析设置

  • 点击 确定,之后解析添加成功

II. 修改 博客根目录 下的 _config.yml 文件

url: 'https://apex.linn.top'

III. 用 VS Code博客根目录 下的 source 目录下新建一个不带任何后缀名的 CNAME 文件

IV. 修改 CNAME 文件,文件内容为你的自定义博客网址

apex.linn.top

V. 重新生成并部署 Hexo 博客

  • hexo clean

  • hexo g

  • hexo d

  • 之后便能通过自定义域名访问博客,如图所示:

自定义域名访问博客

9. [可选] 更换 Hexo 博客主题

这里推荐 Icarus 主题

GitHub 地址:github.com/ppoffice/he…

效果如图:

Icarus 主题效果

I. 更换步骤

  • 在终端中,确保为 博客根目录 的情况下,输入以下 git 命令,回车后等待安装完毕

    git clone github.com/ppoffice/he… themes/icarus

  • 修改 博客根目录 下的 _config.yml 文件

    theme: icarus
    
  • 清理之后重新生成并部署 Hexo 博客

    • hexo clean

    • hexo g

    • hexo d

  • 部署完毕后再刷新博客页面,发现主题更换成功,如图所示:

主题更换后的效果

II. 修改主题的 _config.yml 文件

Icarus 主题的根目录下,找到 _config.yml 文件,用 VS Code 修改

注意:关于文章末尾的打赏,也在本文件设置,同时需要指定支付宝微信收款码所处的地址,可以在 source 目录下新建一个 images 文件夹,在其中存放收款码图片,引用图片的方法如下所示:

# Version of the Icarus theme that is currently used
version: 2.6.0
# Path or URL to the website's icon
favicon: /images/favicon.svg
# Additional HTML meta tags in an array.
meta: 
# Path or URL to RSS atom.xml
rss: 
# Path or URL to the website's logo to be shown on the left of the navigation bar or footer
logo: /images/logo.svg
# Open Graph metadata
# https://hexo.io/docs/helpers.html#open-graph
open_graph:
    # Facebook App ID
    fb_app_id: 
    # Facebook Admin ID
    fb_admins: 
    # Twitter ID
    twitter_id: 
    # Twitter site
    twitter_site: 
    # Google+ profile link
    google_plus: 
# Navigation bar link settings
navbar:
    # Navigation bar menu links
    menu:
        主页: /
        归档: /archives
        分类: /categories
        标签: /tags
        关于: /about
    # Navigation bar links to be shown on the right
    links:
        # GitHub:
        #     icon: fab fa-github
        #     url: 'https://github.com/SummerFalls'
# Footer section link settings
footer:
    # Links to be shown on the right of the footer section
    links:
        # Creative Commons:
        #     icon: fab fa-creative-commons
        #     url: 'https://creativecommons.org/'
        # Attribution 4.0 International:
        #     icon: fab fa-creative-commons-by
        #     url: 'https://creativecommons.org/licenses/by/4.0/'
        # Download on GitHub:
        #     icon: fab fa-github
        #     url: 'https://github.com/ppoffice/hexo-theme-icarus'
# Article display settings
article:
    # Code highlight settings
    highlight:
        # Code highlight themes
        # https://github.com/highlightjs/highlight.js/tree/master/src/styles
        # https://highlightjs.org/static/demo/
        theme: vs2015
        # Show code copying button
        clipboard: true
        # Default folding status of the code blocks. Can be "", "folded", "unfolded"
        fold: unfolded
    # Whether to show article thumbnail images
    thumbnail: true
    # Whether to show estimate article reading time
    readtime: true
# Search plugin settings
# https://ppoffice.github.io/hexo-theme-icarus/categories/Plugins/Search
search:
    # Name of the search plugin
    type: insight
# Comment plugin settings
# https://ppoffice.github.io/hexo-theme-icarus/categories/Plugins/Comment
comment:
    # Name of the comment plugin
    type: 
# Donation entries
# https://ppoffice.github.io/hexo-theme-icarus/categories/Donation/
donate:
    -
        # Donation entry name
        type: alipay
        # Qrcode image URL
        qrcode: /images/Alipay.jpg
    -
        # Donation entry name
        type: wechat
        # Qrcode image URL
        qrcode: /images/Wechat.jpg
# Share plugin settings
# https://ppoffice.github.io/hexo-theme-icarus/categories/Plugins/Share
share:
    # Share plugin name
    type:
# Sidebar settings.
# Please be noted that a sidebar is only visible when it has at least one widget
sidebar:
    # left sidebar settings
    left:
        # Whether the left sidebar is sticky when page scrolls
        # https://ppoffice.github.io/hexo-theme-icarus/Configuration/Theme/make-a-sidebar-sticky-when-page-scrolls/
        sticky: true
    # right sidebar settings
    right:
        # Whether the right sidebar is sticky when page scrolls
        # https://ppoffice.github.io/hexo-theme-icarus/Configuration/Theme/make-a-sidebar-sticky-when-page-scrolls/
        sticky: true
# Sidebar widget settings
# https://ppoffice.github.io/hexo-theme-icarus/categories/Widgets/
widgets:
    -
        # Widget name
        type: profile
        # Where should the widget be placed, left or right
        position: left
        # Author name to be shown in the profile widget
        author: Tomy Stark
        # Title of the author to be shown in the profile widget
        author_title: 四海茫茫
        # Author's current location to be shown in the profile widget
        location: Earth, Solar System.
        # Path or URL to the avatar to be shown in the profile widget
        avatar: /images/avatar.jpg
        # Email address for the Gravatar to be shown in the profile widget
        gravatar:
        # Whether to show avatar image rounded or square
        avatar_rounded: true
        # Path or URL for the follow button
        follow_link: 'https://github.com/SummerFalls'
        # Links to be shown on the bottom of the profile widget
        social_links:
            Github:
                icon: fab fa-github
                url: 'https://github.com/SummerFalls'
            知乎:
                icon: fab fa-zhihu
                url: 'https://www.zhihu.com/people/TomyStark'
            微博:
                icon: fab fa-weibo
                url: 'https://weibo.com/tomystark'
    -
        # Widget name
        type: toc
        # Where should the widget be placed, left or right
        position: right
    -
        # Widget name
        type: links
        # Where should the widget be placed, left or right
        position: left
        # Links to be shown in the links widget
        links:
            博客 - 吴川斌: 'https://www.mr-wu.cn/'
            博客 - 芯跳不止: 'http://www.mazirong.com/'
            工作室 - Muse Lab: 'https://www.muselab-tech.com/'
            工作室 - 屋脊雀: 'http://www.wujique.com/'
    -
        # Widget name
        type: category
        # Where should the widget be placed, left or right
        position: right
    -
        # Widget name
        type: tagcloud
        # Where should the widget be placed, left or right
        position: right
    -
        # Widget name
        type: recent_posts
        # Where should the widget be placed, left or right
        position: left
    -
        # Widget name
        type: archive
        # Where should the widget be placed, left or right
        position: right
    -
        # Widget name
        type: tag
        # Where should the widget be placed, left or right
        position: right
# Other plugin settings
plugins:
    # Enable page animations
    animejs: true
    # Enable the lightGallery and Justified Gallery plugins
    # https://ppoffice.github.io/hexo-theme-icarus/Plugins/General/gallery-plugin/
    gallery: true
    # Enable the Outdated Browser plugin
    # http://outdatedbrowser.com/
    outdated-browser: false
    # Enable the MathJax plugin
    # https://ppoffice.github.io/hexo-theme-icarus/Plugins/General/mathjax-plugin/
    mathjax: true
    # Show the back to top button on mobile devices
    back-to-top: true
    # Google Analytics plugin settings
    # https://ppoffice.github.io/hexo-theme-icarus/Plugins/General/site-analytics-plugin/#Google-Analytics
    google-analytics:
        # Google Analytics tracking id
        tracking_id: 
    # Baidu Analytics plugin settings
    # https://ppoffice.github.io/hexo-theme-icarus/Plugins/General/site-analytics-plugin/#Baidu-Analytics
    baidu-analytics:
        # Baidu Analytics tracking id
        tracking_id: 
    # Hotjar user feedback plugin
    # https://ppoffice.github.io/hexo-theme-icarus/Plugins/General/site-analytics-plugin/#Hotjar
    hotjar:
        # Hotjar site id
        site_id: 
    # Show a loading progress bar at top of the page
    progressbar: true
    # BuSuanZi site/page view counter
    # https://busuanzi.ibruce.info
    busuanzi: true
# CDN provider settings
# https://ppoffice.github.io/hexo-theme-icarus/Configuration/Theme/speed-up-your-site-with-custom-cdn/
providers:
    # Name or URL of the JavaScript and/or stylesheet CDN provider
    cdn: jsdelivr
    # Name or URL of the webfont CDN provider
    fontcdn: google
    # Name or URL of the webfont Icon CDN provider
    iconcdn: fontawesome
  • 清理之后重新生成并部署 Hexo 博客
    • hexo clean

    • hexo g

    • hexo d

III. 添加自定义 404 Not Found 页面

  • 在终端中执行以下命令,创建一个 404page 页面

    hexo new page "404"

  • VS Code 编辑 \source\404\ 目录下的 index.md 文件

    • 其中字段 "thumbnail: " 后的图片需要自行存放在对应目录并改为对应名称,后缀名称大小写敏感

    • 文件内容如下所示(可自定义添加更丰富的内容)

      ---
      title: 404 Not Found 该页面不存在
      date: 2019-09-23 15:40:38
      thumbnail: /images/IMG_6274.JPG
      toc: false
      permalink: /404
      ---
      
      <div style = "text-align: center; margin: auto; width: 100%;">
      
      ## **很抱歉,您所访问的地址并不存在。**
      
      </div>
      
  • 清理之后重新生成并部署 Hexo 博客

    • hexo clean

    • hexo g

    • hexo d

  • 部署完毕后再次访问博客,地址后跟上不存在的文章,会自动跳转到刚刚自定义的 404 页面,如图:

404 页面

IV. 添加关于页面

  • 在终端中执行以下命令,创建一个 aboutpage 页面

    hexo new page "about"

  • VS Code 编辑 \source\about\ 目录下的 index.md 文件

    • 其中字段 "thumbnail: " 后的图片需要自行存放在对应目录并改为对应名称,后缀名称大小写敏感

    • 文件内容如下所示(可自定义添加更丰富的内容)

      ---
      title: 关于我 About Me
      date: 2019-09-19 15:59:10
      thumbnail: /images/Car.jpg
      ---
      
      - <i class="fab fa-fort-awesome-alt"></i> 职业: 复制粘贴工程师
      - <i class="fas fa-at"></i> 邮箱: xxxxx@qq.com
      - <i class="fab fa-qq"></i> QQ: 123456789
      - <i class="fab fa-weixin"></i> WeChat: XXXXXX
      - <i class="fab fa-playstation"></i> PSN ID: XXXXXX
      - 星座: 天蝎座
      - 语言: C/C++/Java/HTML/CSS
      - IDE: [VS Code](https://code.visualstudio.com/), [Vivado Design Suite HLx](https://china.xilinx.com/products/design-tools/vivado.html)
      - EDA: [Altium Designer](https://www.altium.com.cn/), [EasyEDA](https://lceda.cn/)
      - 兴趣: 开源硬件, 开源软件, HiFi, 美食, 音乐
      - 游戏平台: <i class="fab fa-playstation"></i> Play Station 4, Nintendo Switch
      - 运动: 游泳, 骑行
      - 正在学习中的: Altium Designer, TouchGFX
      
  • 清理之后重新生成并部署 Hexo 博客

    • hexo clean

    • hexo g

    • hexo d

  • 部署完毕后再次访问博客,关于 页面已经可以正常访问,如图:

关于页面

V. Icarus 主题小问题修改

  • footer 页脚高度过高的问题

    VS Code 编辑主题目录下的 style.styl 文件

    路径:\themes\icarus\source\css\style.styl

    为文件中的 .footer 类添加一行属性,如下所示:

    padding-bottom: 3rem
    

    添加属性后的 .footer 类如下所示:

    .footer
        background: white
        padding-bottom: 3rem
        .field
            .button
                background: transparent
    

10. Hexo 模板

\scaffolds 目录下的 3 个文件分别为草稿模板页面模板文章模板,修改其内容以在每次新建文章或页面时,能够自动添加部分模板内容。

  • page.md

    ---
    title: {{ title }}
    date: {{ date }}
    thumbnail: /images/flower.jpg
    toc: false
    ---
    
    
  • post.md

    ---
    title: {{ title }}
    date: {{ date }}
    thumbnail: /images/flower.jpg
    toc: true
    categories:
    - uncategorized
    tags:
    ---
    
    <!--more-->
    
    <div style = "text-align: center; margin: auto; width: 100%;">
    
    ![Car](../images/Car.jpg)
    
    </div>
    
    

11. 写文章

注意:关于文章图片,若还没有创建 images 文件夹,可以在 source 目录下新建一个 images 文件夹,在其中存放图片文件。

这里以创建一篇标题名称为 Hello Hexo 的文章为例:

  • 在终端中执行以下命令,创建一篇文章

    hexo new "Hello Hexo"

  • VS Code 编辑 \source\_posts 目录下的 Hello-Hexo.md 文件

    • 其中字段 "thumbnail: " 后的图片需要自行存放在对应目录并改为对应名称,后缀名称大小写敏感

    • 文件内容如下所示:

      ---
      title: Hello-Hexo
      date: 2019-09-19 15:59:10
      thumbnail: /images/flower.jpg
      toc: true
      categories:
      - Blog
      - Hexo
      tags:
      - Hexo
      ---
      
      ## <i class="fab fa-fort-awesome-alt"></i> 你好 Hexo
      
      正文...
      
      <!--more-->
      
      这里是在主页被隐藏的内容...
      
      <div style = "text-align: center; margin: auto; width: 100%;">
      
      ![Car](../images/Car.jpg)
      
      </div>
      
      
  • 清理之后重新生成并部署 Hexo 博客

    • hexo clean

    • hexo g

    • hexo d

  • 部署完毕后再次访问博客,刚刚发布的文章已经出现在主页上,如图:

添加新文章

12. 至此所有步骤已完成