搭建Hexo教程

这里是在Windows安装记录。

Hexo是一个快速，简单，强大的博客框架。通过MarkDown来编写文章，Hexo快速为你生成静态文件和美观的主题。

一 安装

安装Hexo之前，需要安装Node.js和Git

1.1 安装Node.js:

windows:下载安装. 安装后输入npm查看是否安装成功。
mac:使用apk安装方便node -v查看版本，或者使用更好的方式nvm安装node

2.1 安装Git

Windows：下载地址
Linux：使用homebrew安装git方便

2.3 安装Hexo

$ npm install -g hexo-cli

Windows cmd出现斜杠一样的东西一直转一直转。说明正在安装。
linux：当提示权限不够时，使用sudo安装

二 初始化

Hexo安装好后，创建一个文件夹用于放置Hexo的内容。这里创建在D盘根目录下：hexo_pages。运行下面命令，初始化hexo_pages：

$ hexo init <folder>
$ cd <folder>
$ npm install

这里的folder替换成你创建的文件夹名,进入hexo_pages上一层目录执行第一个命令。
hexo init命令：Hexo 即会自动在目标文件夹建立网站所需要的所有文件。
npm install命令：安装所需要的依赖包。

执行完后，查看你的目录结构：

.
├── _config.yml
├── package.json
├── scaffolds
├── source
|   ├── _drafts
|   └── _posts
└── themes

结构说明：
_config.yml：可以在这里配置需要的配置,配置教程。
package.json：应用程序数据。EJS, Stylus 和 Markdown渲染器会自动安装。如果想要卸载他们，也是可以的。
scaffolds：Scaffold 文件夹，当你创建一个新文章时，Hexo放入Scallffold。
themes：主题。

三 查看本地博客

进入hexo目录，运行命令：

hexo generate
hexo server

访问：http://localhost:4000/
出现博客的网页，说明搭建完整。

四 配置_config.yml

Site

title：你网站的title
subtitle：你网站的二级title
description：网站描述
author：你的名字
language：你网站的语言，默认是en。使用2-lettter ISO-639-1 code。
timezone：你网站的时区。Hexo默认使用你电脑设置的时区。时区列表。如：America/New_York, Japan, and UTC.

URL

url：你网站的URL。
root：你网站的根目录。
permalink：你文章的永久链接，默认为:year/:month/:day/:title/。
permalink_default：每个部分的永久链接的默认值。

Directory

sorce_dir:资源目录。内容存放的目录。默认为source。
public_dir:公开目录。静态网站生成的目录。默认public。
tag_dir:Tag目录。默认tags。
archive_dir:Archive目录。默认archives。
category_dir：gategory目录。默认categories。
code_dir:code目录。默认downloads/code。
i18n: i18n目录。默认:lang。
skip_render:不渲染的目录。你可以使用 glob expressions匹配路径。

Writing

new_post_name:新文章的文件名格式，默认:title.md
default_layout:defualt layout,默认post.
titlecase:文章标题是否首字母大写，默认false .
external_link:在新标签页打开外部链接，默认true.
filename_case:转换文件名1小写;2大写,默认0.
render_drafts:渲染草稿，默认false。
post_asset_folder:Enable the asset Folder,默认false。
relative_link:使链接为相对于根目录的链接，默认false。
future:显示未来的文章？默认false。
highlight：代码块区设置

Category & Tag

default_category ： Default category，默认uncategorized。
category_map：Category slugs。
tag_map ：Tag slugs。

Date / Time format

Hexo使用Moment.js处理时间。
date_format ： Date format ，默认 MMM D YYYY
time_format ： Time format ，默认 H:mm:ss

Pagination

per_page：每页展示的文章数. 0表示不展示，默认为10。
pagination_dir：Pagination directory，默认为page。

Extensions

theme：主题名称. false表示不显示主题。
deploy：Deployment setting

五 命令

init 初始化website

hexo init [folder]
如果folder未指定，则会在当前目录初始化website。

new 创建article

hexo new [layout] <title>
创建一个新的article，如果layout未指定，Hexo将会使用_config.yml中的default_layout值。如果title包含了空格，请用引号包含该title。
注意：hexo的title是使用yml或者json指定的，如果直接创建md文件不会生成，使用该命令，则会自动将该文件名生成为title名。

新建页面

hexo new page "pageName" #新建页面

generate 生成静态文件

hexo generate
参数：
-d， –deploy 生成后进行部署。
-w，–watch 查看changes

publish：发布

hexo publish [layout] <filename>
Publishes a draft.

server：启动本地服务

hexo server
启动本地服务，localhost:4000
参数：
-p, –port ： Override default port
-s, –static ： Only serve static files
-l, –log ： Enable logger. Override logger format.

deploy：部署网站

hexo deploy
参数：
-g, –generate：Generate before deployment

render：Renders files.

hexo render <file1> [file2] ...
参数；
-o, –output ： Output destination

migrate：从其他博客系统迁移内容

hexo migrate <type>

clean ： 清理缓存文件(db.json)和生成的文件(public)

hexo clean

list: 列出所有routes

hexo list <type>

version：查看hexo版本

hexo version

可选命令：

Safe mode ： 禁用加载插件和脚本。试试这个,如果你安装新的插件遇到问题后。
hexo --safe
Debug mode：日志详细信息到终端和debug.log。试试这个Hexo如果你遇到任何问题。如果你看到错误,请raise a GitHub issue.。
hexo --debug
Silent mode：沉默的输出终端。
hexo --silent
Customize config file path：使用一个自定义配置文件(而不是_config.yml)。
$ hexo --config custom.yml
Display drafts：显示文章草稿(存储在源/ _drafts文件夹)。
hexo --draft
Customize CWD：自定义当前工作目录的路径。
$ hexo --cwd /path/to/cwd

常用简写

$ hexo n == hexo new
$ hexo g == hexo generate
$ hexo s == hexo server
$ hexo d == hexo deploy

常用组合

$ hexo d -g #生成部署
$ hexo s -g #生成预览

六 开始写文章

创建一篇新文章

hexo new [layout] <title>
layout:Hexo提供三种，每种都会保存在不同的path中，custom自定义的保存在source/_posts文件夹中。

        Layout    Path
post    source/_posts
page    source
draft   source/_drafts

layout：默认的是post，你也可以提供自己想要的。通过修改_config.yml中的default_layout来修改默认的layout。
文件名：默认情况下,Hexo使用文章标题的文件名，您可以编辑_config.yml的new_post_name设置改变默认的文件名。
例如：:year-:month-:day-:title.md将文件名前缀加上创建日期。
您可以使用以下占位符:

Placeholder	Description
:title	Post title (lower case, with spaces replaced by hyphens)
:year	Created year, e.g. 2015
:month	Created month (leading zeros), e.g. 04
:i_month	Created month (no leading zeros), e.g. 4
:day	Created day (leading zeros), e.g. 07
:i_day	Created day (no leading zeros), e.g. 7

使用more设置摘要

在需要在首页显示文章摘要的地方加上more标签：

草稿

以前,我们提到了一个特殊的布局Hexo:Draft。 文章使用此布局初始化保存到source/ _drafts文件夹。您可以使用publish命令移动source/ _post文件夹。publish命令以类似new命令的方式工作。
$ hexo publish [layout] <title>
Draft默认不显示。您可以添加–draft选项，在运行Hexo时，或者修改_config_yml中render_draft的设置。

Scaffolds

当创建帖子,Hexo将构建文件基于Scaffolds文件夹中的相应文件。
$ hexo new photo "My Gallery"
当您运行这个命令,Hexo将试图从scaffolds中找photo.md.然后创建post。
在Scaffolds中下面的占位符中可用:

Placeholder	Description
layout	Layout
title	Title
date	File created date

七 预配置

Front-matter是用YAML或JSON为开头的文件用于配置设置你的文章。
Front-matter在YAML中是以三个破折号结束，在JSON中是以三个分号结束。
YAML:

---
title: Hello World
date: 2013/7/13 20:46:25
---

JSON

"title": "Hello World",
"date": "2013/7/13 20:46:25"
;;;

需要设置的key-value和默认值

|Setting | Description | Default|
|———-|—–|
|layout| Layout |
|title | Title|
|date | Published date | File created date|
|updated | Updated date |File updated date|
|comments | Enables comment feature for the post |true|
|tags | Tags (Not available for pages) |
|categories | Categories (Not available for pages) |
|permalink | Overrides the default permalink of the post |

文章分类和标签

只有文章支持分类和标签的使用。类别有层次结构。标签都定义在同一层次级所以它们出现的顺序并不重要。

Example：
categories:
- Sports
- Baseball
tags:
- Injury
- Fight
- Shocking

八 发布

Hexo提供了一个快速和容易的部署策略。你只需要一个简单的命令将网站部署到您的服务器。
$ hexo deploy
在你第一次部署之前,您必须在_config.yml修改一些设置。一个有效的部署设置必须有一个type字段。例如:

deploy:
  type: git

您可以一次部署多个。Hexo将依次执行每个部署命令:

deploy:
- type: git
  repo:
- type: heroku
  repo:

部署到Git

要部署要github首先要安装hexo-deployer-git,进入要部署的文件夹，运行下面的命令：

$ npm install hexo-deployer-git --save

然后修改该项目的配置文件

deploy:
  type: git
  repo: <你的repository地址>
  branch: [分支名称master或者其他]
  message: [提交注释，默认是now('YYYY-MM-DD HH:mm:ss')]

部署到其他库：如Heroku,Rsync,看在线教程
注意：每次修改了本地文件要先generate 然后 deploy。

九 修改主题

所有的主题放在\hexo\themes\下面。当前使用哪个主题是在hexo_config.yml文件中配置的。
所以我们要更改主题只要简单的步骤：
1.进入github page根目录，从github上clone下来喜欢的主题放在\hexo\themes\下面。
git clone <repository> themes/<theme-name>
2.将当前使用的主题在hexo_config.yml文件中修改为刚下载的主题。
theme: 主题名称

更新主题

进入当前主题

cd themes/主题名称
git pull

重新部署

hexo generate
hexo deploy

十 设置永久链接

你可以在_config.yml中指定永久链接或者在每篇文章的开头指定。
变量

Variable	Description
:year	Published year of posts (4-digit)
:month	Published month of posts (2-digit)
:i_month	Published month of posts (Without leading zeros)
:day	Published day of posts (2-digit)
:i_day	Published day of posts (Without leading zeros)
:title	Filename
:id	Post ID
:category	Categories. If the post is uncategorized(未分类的), it will use the default_category value.
你可以定义每个变量的默认值的永久链接permalink_defaults字段：

permalink_defaults:
  lang: en

例子；
Given a post named hello-world.md in the source/_posts folder with the following content.

title: Hello World
date: 2013-07-14 17:01:34
categories:
- foo
- bar

Setting	Result
:year/:month/:day/:title/	2013/07/14/hello-world
:year-:month-:day-:title.html	2013-07-14-hello-world.html
:category/:title	foo/bar/hello-world

十一 多语言

创建一个多语言网站,您可以修改new_post_name和永久链接设置是这样的:

new_post_name: :lang/:title.md
permalink: :lang/:title/

当你创建一个新帖子,帖子将被保存到:

$ hexo new "Hello World" --lang tw
# => source/_posts/tw/Hello-World.md

the URL will be:
http://localhost:4000/tw/hello-world/

十二 创建主题

很容易建立一个Hexo主题——你只需要创建一个新文件夹。开始使用您的主题,修改主题设置站点的_config.yml。一个主题应该有以下结构:

.
├── _config.yml
├── languages
├── layout
├── scripts
└── source

_config.yml：题配置文件。修改这并不需要重新启动服务器。
languages：语言文件夹。更多信息见国际化(i18n)。
layout：这个文件夹包含主题的模板文件,它定义了你的网站的外观。Hexo提供swing为默认模板引擎,但您可以很容易地安装额外的插件，如EJS,Haml或Jade等替代引擎。Hexo选择模板引擎基于模板的文件扩展名。例如:

layout.ejs   - uses EJS
layout.swig  - uses Swig

scripts：Hexo将自动加载所有JavaScript文件在这个文件夹在初始化期间。see plugins。
source：替代你的assets(例如CSS和JavaScript文件)。Hexo忽略了隐藏的文件和以下划线开头的文件或文件夹。Hexo处理和保存所有可渲染的文件到public文件夹。Non-renderable文件直接复制到public文件夹。

发布主题

当你已经完成了建筑的主题,您可以发布到 theme list。在这样做之前,你应该运行theme unit test以确保一切能运行正常。发布一个主题的步骤非常类似于updating documentation。

1.Fork hexojs/site

2.Clone the repository to your computer and install dependencies.

git clone https://github.com/<username>/site.git
cd site
npm install

3.Edit source/_data/themes.yml and add your theme. For example:

- name: landscape
  description: A brand new default theme for Hexo.
  link: https://github.com/hexojs/hexo-theme-landscape
  preview: http://hexo.io/hexo-theme-landscape
  tags:
    - official
    - responsive
    - widget
    - two_column
    - one_column

4.Add a screenshot

(with the same name as the theme) to source/themes/screenshots. It must be a 800*500px PNG.

5.Push the branch.

6.Create a pull request and describe the change.

插件

直接生成想要的媒体等资源，如video，等查看所有插件

错误

渲染错误：写文章过程中，右类似于 %} , {{ , }} 的符号，hexo没法渲染，如下错误

Template render error:  unexpected token: %}

解决方法：使用 {% raw %} {% endraw %} 将无法渲染的这些字符包裹起来即可

资源文件夹

资源文件夹

所有详细内容请看官方文档

问题

本地启动hexo server成功，但是localhost打开一片空白
解决：可能本地某个进程占用了默认的4000端口，修改启动的端口号，如hexo server -p 4001就好。

同个电脑多个git账号发布

默认的hexo deploy是读取global的git配置，如果本机有更重要的项目占用的global，hexo只能用项目级的git配置。

git generate，生成public文件夹，该文件夹是真正部署上去的文件，将该文件配置为项目级的git，直接将该文件夹push到xxx.github.io项目即可。

hexo部署时会在根目录下生成一个deploy git目录中间包括了与public文件相同的文件夹。

部署使用global的git账号。

hexo deploy的时候，是将deploy git文件中的静态文件push到库中。

如果同一个电脑有多个git账号，如果设置了global的git账号后，容易导致混淆。

所以应该：每次generate了以后，然后会生成publish的文件夹中，直接将publish弄成git库然后直接push到github.io库中。