学习一门新的知识,最重要的还是要官方文档。之前不愿意去看官方文档,到处搜索如何搭建,如何设置等等,但是有时也无法找到自己想要的内容,于是只能研究官方文档了,奈何是英文的,从没有完整看完。最近静下心来,看了一遍,这里的内容是根据官网Docs加上自己的一些理解。

(一)开始准备

官方Hexo Docs分为了4个部分,分别为:开始准备、基础用法、自定义、其他。Hexo的主要内容是在基础用法和自定义这两部分上。

这部分主要介绍了什么是Hexo、如何安装以及基本配置。

Hexo是一个快速的、简单的、功能强大的博客框架。你可以通过Markdown语言写文章,然后hexo帮你生成一个带有漂亮主题的静态页面。

1、安装

安装hexo的前提是要有Node.js以及Git,至于什么是Git和Node以及如何安装他们可以自行搜索了解。

安装完Node以及Git后,通过下面的命令安装Hexo:

npm install -g hexo-cli

2、启动

在电脑中找个目录,并进入目录,执行下面几个命令,hexo就准备就绪了。

hexo init
npm install

上面两条命令,第一条是初始化目录,会自动生成一些基础文件和目录,第二条命令是安装运行hexo的一些必要的组件。

OK,运行完,你会看到你的当前目录下,会自动创建一些目录,如下:

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

下面依次介绍上面各个文件或者目录的用途:

  • _config.yml站点配置文件,很多全局配置都在这个文件中。
  • package.json 应用数据。从它可以看出hexo版本信息,以及它所默认或者说依赖的一些组件。
  • scaffolds 模版文件。当你创建一篇新的文章时,hexo会依据模版文件进行创建,主要用在你想在每篇文章都添加一些共性的内容的情况下。
  • scripts 放脚本的文件夹, 就是放js文件的地方
  • source 这个文件夹就是放文章的地方了,除了文章还有一些主要的资源,比如文章里的图片,文件等等东西。这个文件夹最好定期做一个备份,丢了它,整个站点就废了。
  • themes 主题文件夹。

3、配置

前面说了,主要配置就是_config.yml这个文件了,所以来看看怎么配置它了。配置也是分了几个大块的。

(1)首先是Site部分,也就是站点的一些参数设置:

  • title 站点名字,也就是html的title,会显示在浏览器标签上。
  • subtitle 站点副标题,会显示在首页上,可以不填。
  • description 站点描述,可以不填。
  • author 作者
  • language 语言
  • timezone 站点时区,默认是电脑时间

(2)接下来是URL部分设置:

  • url 站点网址
  • root 站点根目录
  • permalink 文章的永久网址链接,默认是:year/:month/:day/:title/,指的什么意思?比如我一篇叫『love』的文章是在2012年1月1日写的,那么它对应的链接就是http://yoururl/2012/01/01/love/
  • permalink_default

如果网址是次级目录,比如:http://example.com/blog,那么就要设置urlhttp://example.com/blog,并且root要设置为/blog/

(3)再接下来就是目录配置:

  • source_dir source目录,默认值为source
  • public_dir public目录,静态网站生成的地方,默认值为public
  • tag_dir tag目录
  • archive_dir Archive目录
  • category_dir 分类目录
  • code_dir 代码目录
  • i18n_dir i18n目录
  • skip_render 不想被渲染的路径

上面这一部分的值,我基本上没有改过,默认的就行了。

(4)接着是写作配置了:

  • new_post_name 新建文章默认文件名,默认值为 :title.md,比如你执行命令hexo new hello,就会默认在_post目录下创建一个hello.md的文件。
  • default_layout 默认布局
  • titlecase
  • external_link 在新标签中打开一个外部链接,默认为true
  • filename_case 转换文件名,1代表小写;2代表大写;默认为0,意思就是创建文章的时候,是否自动帮你转换文件名,默认就行,意义不大。
  • render_drafts 是否渲染_drafts目录下的文章,默认为false
  • post_asset_folder 是否启用Asset Folder,默认为false,至于什么是Asset Folder,后面有讲解。
  • future 是否显示未来日期文章,默认为true
  • highlight 代码块设置

这一部分也可以基本不变,默认值就行。

(5)接下来是分类和标签的设置:

  • default_category 默认分类,默认为无分类,当然你可以设置一个默认分类。
  • category_map 分类,不明白其作用
  • tag_map 标签,不明白其作用

(6)日期和时间格式配置:

Hexo使用的Moment.js来处理时间的。

  • data_format 日期格式,默认为MMM D YYYY,不过我将它改成了YYYY-MM-DD,符合个人口味,其他格式模版可以查看Moment.js
  • time_format 时间格式,默认为H:mm:ss

(7)分页设置:

  • per_page 一页显示多少篇文章,0 为不分页,默认值为 10
  • pagination_dir 分页目录,默认值为page

(8)最后就是扩展配置:

  • theme 主题配置,此处填上主题名就OK了,当然在themes目录下一定要有你配置的主题文件夹。
  • deploy 部署配置,将本地public目录也就是网站部署到服务器上的配置。如何部署?Docs文档『基础用法』部分有说明。

4、命令

这块主要介绍了hexo的一些命令的使用方法。

  • hexo init [folder],使用该命令初始化一个站点,不加目录参数,就初始化当前目录
  • hexo new [layout] <title>,创建一篇文章,如果不指定layout,那么就使用_config.ymldefault_layout的值,标题中如果有空格,将整个title放到引号中。比如,hexo new "hello world"创建一篇叫hello world的文章。
  • hexo generate,简单的说,这个命令就是将md格式的文章,生成静态网页。这个命令可以简写为hexo g,它有两个参数选项:
    • -d,--deploy 生成完后直接部署
    • -w,--watch 查看文件的改变
  • hexo publish [layout] <filename>,发布一个草稿
  • hexo server,启动一个本地服务,可以在本地查看网站,默认启动http://localhost:4000,貌似这个不是默认,运行命令的时候可以查看提示消息。它也有一些参数:
    • -p,--port 指定端口
    • -s,--static 仅服务静态文件
    • -l,--log 开启日志
  • hexo deploy 部署站点,可以缩写hexo d,有一个参数,hexo d -g表示在部署前先重新生成一下站点
  • hexo render <file1> [file2] ... 渲染文件,具体我也不太明白这是干嘛的
  • hexo migrate <type> 迁移其他博客系统的命令,具体怎么使用DOCS后面有介绍。
  • hexo clean 删除缓存文件db.json以及生成的public目录,当你修改了某些样式或者配置时,如果发现hexo g后也没有反应,就可以执行一下这个命令。
  • hexo list 没用过
  • hexo version 显示版本信息
  • hexo --safe 安全模式,使所有插件和脚本不生效
  • hexo --dehug 调试模式
  • hexo --silent 静默模式,不在终端上显示任何信息
  • hexo --config custom.yml 使用一个自定义配置文件替换默认_config.yml
  • hexo --draft 显示草稿文章(位于source/_drafts目录下)
  • hexo --cwd /path/to/cwd 自定义当前工作目录路径,假如你没在工作目录下,可以使用这个命令指定一下工作目录路径。

5、迁移

从其他博客站点迁移文章到hexo中,像类似Jekyll和Octopress只要把.md的文章拷贝过来就OK了,还有一些需要安装插件。

(1)RSS

首先安装插件npm install hexo-migrator-rss --save,待安装完成后,运行命令hexo migrate rss <source>就可以从RSS迁移所有文章了。source可以是一个文件路径或者URL

(2)Jekyll & Octopress

直接拷贝_posts文件夹里的文章到hexo的source/_posts就OK了,然后修改new_post_name参数为对应文章title命名规则就行了,如:year-:month-:day-:title.md

(3)WordPress

安装插件npm install hexo-migrator-wordpress --save,使用WordPress导出功能导出文章,然后运行命令hexo migrate wordpress <source>source为导出文件

(4)Joomla

安装插件npm install hexo-migrator-joomla --save,使用J2XML组件导出Joomla文章,然后运行命令hexo migrate joomla <source>source为导出文件

导出或者导入,可能出现一些问题,可以自行百度搜索。

转载保存:Hexo | LP's Blog

(二)基本用法

上一篇将『开始准备』部分大致说完了,接下来是『基本用法』部分。

这部分Docs分了8块内容,分别从写作、前置声明、标签插件、资源目录、数据文件、服务器、生成器、部署。也许翻译得不得当,但是我尽量把主要内容呈现出来并加上自己的理解。

1、写作

写作之前当然得先创建一个.md文件,使用命令hexo new [layout] <title>,其中layout默认为post,前面提过。

(1)Layout布局

Hexo提供了3种默认的布局,postpagedraft,路径分别为:source/_postssourcesource/_draft。如果你将在文章前置申明中,将layout设置为false,那么这篇文章将不会有任何的布局。

(2)Filename文件名

Hexo会默认将文章的标题当做文件名,但是你可以编辑_config.yml配置文件中的new_post_name来改变默认的文件名。

例如:使用hexo new hello命令创建一篇为hello文章,Hexo会默认在_posts目录下给你创建一个名为hello.md的文件。假如你将new_post_name改为了:year-:month-:day-:title.md,那么hexo就自动帮你创建名为2015-05-16-hello.md(当前日期为2015年5月16)

  • :title 文章标题
  • :year 创建年份
  • :month 月份,如4月为04
  • :day 日期
  • i_month 月份,单数字,比如4月就是4
  • i_day 同上

(3)Drafts草稿

Hexo提供草稿功能,在_drafts目录下的文章不会发表到网站上,你可以通过命令hexo publish [layout] <title>发布你的草稿,改命令会将文章移到_posts目录下。但是也可以设置_config.yml配置文件的render_drafts字段,使草稿默认发布到站点中。

(4)Scaffolds模版

当你使用new命令创建一篇文章的时候,Hexo会根据scaffolds目录中的模版帮你生成文章。假如执行hexo new photo "My Gallery",Hexo会尝试在scaffolds目录中去寻找photo.md的模版文件,然后基于它创建标题为My Gallery的文章。

它的用处就是能够在模版中写入你某一类文章都要添加的共同内容,这样你基于模版创建文章的时候,就不用再重复写入那部分内容。

2、前置申明

顾名思义,就是写在文章前面的一块内容,为了对文章进行某些设置。它有两种书写方式:

  1. YAML方式,以三短线结束

    title: Hello World
    date: 2013/7/13 20:46:25
    ---
    
  2. JSON方式,以三分号结束

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

下面看看有哪些参数可以设定:

  • layout 布局,一般不用写,默认就行
  • title 标题,这个必须要有
  • date 时间
  • updated 修改时间
  • comments 是否开启评论,默认为true
  • tags 文章标签
  • categories 文章分类
  • permalink 文章永久链接,一般不用写,默认就行

在写标签和分类的时候,可能会有多个的情况,多个标签可以无序排列的方式书写,而分类可能会有多级分类的情况。如何书写举例如下:

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

3、标签插件

这里说的标签插件不同于文章中的标签,它可以帮助你在文章中快速嵌入一些特殊的内容。

(1)Block Quote-块引用

插入带有作者信息的应用,体现在Html上就是在blockquote标签下加入了footer标签。但是会给文章带来不一样的显示效果,书写格式非常简单。

{% blockquote [author[, source]] [link] [source_link_title] %}
content
{% endblockquote %}

看下面的例子就大概知道怎么书写了,第一种最简单的方式就等于markdown里的>语句。

显示效果为(主题为light-ch):

(2)Code Block代码块

在文章中插入代码块可以使用下面方式书写

{% codeblock [title] [lang:language] [url] [link text] %}
code snippet
{% endcodeblock %}

同样举个例子,用法一目了然。

显示效果如下:

(3)Pull Quote

这个插件可以帮助您在文章中插入重要引述。

{% pullquote [class] %}
content
{% endpullquote %}

(4)jsFiddle

在文章中嵌入jsFiddle片段。

{% jsfiddle shorttag [tabs] [skin] [width] [height] %}

(5)Gist

嵌入Gist片段

{% gist gist_id [filename] %}

(6)iFrame

插入网页框架

{% iframe url [width] [height] %}

(7)Image

插入图片,可以自定义大小

{% img [class names] /path/to/image [width] [height] [title text [alt text]] %}

(8)Link

插入带有target="_blank"属性值的链接。

{% link text url [external] [title] %}

(9)Include Code

从资源目录中插入代码片段。

{% include_code [title] [lang:language] path/to/file %}

(10)Youtube

在文章中插入Youtube视频。天朝的孩子就不用试了

{% youtube video_id %}

(11)Vimeo

在文章中插入Vimeo视频。

{% vimeo video_id %}

(12)Include Posts

包含其他文章的链接。

{% post_path slug %}
{% post_link slug [title] %}

(13)Include Assets

包含文章资源。(具体怎么使用,还不太明白,后续再补充)

{% asset_path slug %}
{% asset_img slug [title] %}
{% asset_link slug [title] %}

(14)Raw

一些内容不想被主题渲染,可以使用该插件呈现原始状态。

{% raw %}
content
{% endraw %}

4、资源目录

Assets指的是那些不在source目录下的资源,比如图片、CSS文件或者Javascript文件。Hexo提供一种更方便的方法来管理这些资源(Assets)。想使其生效,首先修改post_asset_folder字段的设置,将其值改为true

当生效后,在你创建文章的时候,Hexo会创建一个同名目录,你可以将该文章关联的资源全部放到该目录下。这样就可以更加方便的使用它们了。

使用方法就是上面介绍过的标签插件。

{% asset_path slug %}
{% asset_img slug [title] %}
{% asset_link slug [title] %}

5、数据文件

有时,你可能会使用一些不在post中的模版数据,或者你想复用这些数据,那么你可以试用一下Hexo3中的『Data files』功能。这个特性加载source/_data目录中的YAML或者JSON文件,从而用到你的网站中。

例如,在source/_data目录中添加menu.yml文件。内容如下:

Home: /
Gallery: /gallery/
Archives: /archives/

在模版中,你可以这样使用它。

{% for link in site.data.menu %}
  <a href="{{ link }}">{{ loop.key }}</a>
{% endfor %}

6、服务器

(1)Hexo server

在Hexo3中,服务器模块从主模块中分开了,你可以通过安装hexo-server来使用它。

npm install hexo-server --save

安装完成后,通过运行命令hexo server来启动本地服务。可以通过http://localhost:4000或者http://0.0.0.0:4000来访问你的网站。服务启动后,Hexo会监视文件的改动情况并且自动更新,也就是说你修改网站内容后不必重启服务器就可以见到效果。

如果你想修改端口,可以通过hexo server -p 5000命令来指定端口。

hexo server -s启动静态模式,在静态模式中,只有public文件夹下的文件才会被放到服务器上,并且文件监听功能关闭。你可以在运行hexo g命令后运行该命令,通常用于生产系统中。

hexo server -i 192.168.1.1指定IP访问,可以替代默认的0.0.0.0.

(2)Pow

Pow是Mac上一个零配置的服务架构。通过curl get.pow.cx | sh命令下载并安装该软件;然后链接到项目文件夹中,步骤如下:

cd ~/.pow
ln -s /path/to/myapp index

通过上面命令,会在~/.pow目录下创建一个index的链接文件指向你的hexo根目录,然后你就可以通过访问http://index.dev就可以看到你的主页了。

7、生成器

这个很简单,hexo generate一条命令生成静态站点。可以使用缩写hexo g,还可以显示你修改的文件并且重新生成,使用命令hexo g --watch,还用两种用法可以跟部署结合起来,hexo g -d or hexo d -g,指的是生成后马上部署站点。

8、部署

部署的方式有多种,这里我主要介绍一下Git的方式,因为GitHub提供Pages功能,可以直接将站点部署到Github上。

主要就是设置_config.yml配置文件,

deploy:
    type: git
    repo: https://github.com/pengloo53/pengloo53.github.io.git
    branch: master

这样就设置好了,注意将repo改成自己的。其他方式类似。部署命令很简单,hexo d就OK了。

PS: 有些不太明白的地方后续再更新。

转载保存:Hexo | LP's Blog

(三)高级进阶

这一部分的主要是一些高级进阶的功能,想自定义自己的主题,就需要这部分的内容。

1、永久链接

你可以通过_config.yml或者文章的头部申明来设置文章的永久链接。

(1)变量

下面列举了可以使用在永久链接里的变量,除了下面这些,你可以使用固定链接中的任何属性。

  • :year 4位的年,比如2015
  • :month 2位的月,比如06
  • :i_month 去掉前面0的月,比如9代表9月
  • :day 两位的天,比如05代表5号
  • :i_day 同理
  • :title 文件名
  • :id 文章ID
  • :category 类别;如果文章没有指定,那么就是default_category字段设置的那个。

你也可以自定义每个变量,在permalink_defaults中这样设置:

permalink_defaults:
    lang: en 

(2)举例说明

假设在_posts目录下有一篇名为hello-world.md的文章,声明如下:

title: Hello World
date: 2015-06-01
categories:
- foo
- bar
  • 设置为::year/:month/:day/:title/ 结果为:2015/06/01/hello-world
  • 设置为::year-:month-:day-:title.html 结果为:2015-06-01-hello-world.html
  • 设置为::category/:title 结果为:foo/bar/hello-world

(3)多语言支持

你可以通过new_post_namepermalink字段的设定,来创建一个多语言的网站。

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

当你创建一个新的文章的时候,hexo new "Hello World" --lang tw,hexo会创建source/_posts/tw/Hello-World.md,那么http://localhost:4000/tw/hello-world/便会指向该文章。

2、主题

hexo根目录中的theme目录就是主题的所在地,设置主题非常简单,只需将_config.yml中theme字段值设为主题名就行了。下面看一下一个主题的目录结构:

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

(1)主题全局设置

_config.yml配置文件,跟hexo的全局配置文件名一样。只是在不同的目录中,在该配置文件中的改动不需要重启服务,就可以实时体现在站点中。

(2)语言

语言文件夹,详细信息可以查看Localization(i18n)的说明,下面再介绍。

3、模版

模版基本上就是网站的布局了,如果你想要自己亲手制作一个Hexo的主题,那么就要深入了解这块内容了,每一个主题至少都要包含一个index模版,下面是各页面对应的模版名称:

  • index 首页
  • post 文章
  • page 分页
  • archive 归档
  • category 分类归档
  • tag 标签归档

(1)Layouts(布局)

如果页面结构类似,举个例子,两个模版都含有header以及footer,你就可以考虑通过「布局」让两个模板共享相同的结构。一个布局文件必须要能显示 body 变量的内容,如此一来模板的内容才会被显示,例如:

<!--index.ejs-->
index

<!--layout.ejs-->
<html>
  <body><%- body %></body>
</html>

生成的结果如下:

<!DOCTYPE html>
<html>
  <body>index</body>
</html>

每个模板都默认使用layout布局,您可在文章的前置申明中指定其他布局,比如“post”或者“page”或是设为false来关闭布局功能(如果不填默认是post,这个在_config.yml中可以设置默认值),您甚至可在布局中再使用其他布局来建立嵌套布局。

也许你看到官方Docs这么说,还是不明白说的是什么意思,后面我会通过创建个人简历的布局示例来详细讲解这一块内容。

(2)Partials(局部模版)

局部模版可以让你在不同的模版中分享相同的组件,例如Header、Footer或者Sidebar侧边栏等等,可以利用局部模版功能将各个组件分割成独立的文件,便于维护。例如:

<!--partial/header.ejs-->
<h1 id="logo"><%= config.title %></h1>

<!--index.ejs-->
<%- partial('partial/header') %>
<div id="content">Home page</div>

生成后就是:

<h1 id="logo">My Site</h1>
<div id="content">Home page</div>

这个很容易理解,就是将局部模块里的内容,原封不动的拷贝到引用它的文件中。

(3)Local Variables(本地变量)

这里的变量就是针对局部模版来使用的,您可以在局部模块中指定局部变量来进行传递。例如:

<!--partial/header.ejs-->
<h1 id="logo"><%= title></h1>

<!--index.ejs-->
<%- partial('partial/header', {title: 'Hello World'}) %>
<div id="content">Home page</div>

生成后就是:

<h1 id="logo">Hello World</h1>
<div id="content">Home page</div>

这个也不难理解,就是传递变量的过程。

(4)Optimization(最优化)

假如你的主题特别复杂,因为要生成的文件过于庞大,这样会导致hexo生成性能下降,除了优化主题外,你还可以通过Fragment Caching(局部缓存)的功能来处理。它的主要功能就是缓存局部的内容,减少文件查询。常用在那些很少变动的模块中,比如Header、Footer等等,例如:

<%- fragment_cache('header', function(){
  return '<header></header>';
});

如果使用局部模版的话,如下:

<%- partial('header', {}, {cache: true});

但是需要注意的是,如果开启了relative_link参数的话,就不要使用局部缓存的功能,因为relative link在每个页面可能不同。

4、变量

(1)全局变量

  • site 网站变量
    • site.posts 所有文章
    • site.pages 所有分页
    • site.categories 所有分类
    • site.tags 所有标签
  • page 针对改页面的内容以及前置申明中所设定的变量
  • config 配置文件中的变量
  • theme 主题配置文件中的变量
  • _ lodash函数库
  • path 当前页面的路径(不含根路径)
  • url 页面完整网址
  • env 环境变量

(2)页面变量

Page(page) 这里指的是hexo new page创建的那个页面

  • page.title 文章标题
  • page.date 文章建立日期
  • page.updated 文章更新日期
  • page.comments 留言是否开启
  • page.layout 布局名称
  • page.content 文章完整内容
  • page.excerpt 文章摘要
  • page.more 除了摘要的其他内容
  • page.source 文章原始路劲
  • page.full_source 文章完整原始路径
  • page.path 文章网址(不含根路径),通常在主题中使用url_for(page.path)
  • page.permalink 文章永久网址
  • page.prev 上一篇文章,如果此为第一篇文章则为null
  • page.next 下一篇文章,如果此为最后一篇文章则为null
  • page.raw 文章原始内容
  • page.photos 文章的照片(用于相册)
  • page.link 文章的外链(用于链接文章)

Post(post) 这里指的是文章页面,与page布局相同,添加如下变量:

  • page.pulished 文章非草稿为true
  • page.categories 文章分类
  • page.tags 文章标签

首页(index)

  • page.per_page 每一页显示的文章数
  • page.total 文章数量
  • page.current 当前页码
  • page.current_url 当前页的URL
  • page.posts 当前页的文章
  • page.prev 前一页页码,如果为第一页,该值为0
  • page.prev_link 前一页URL,如果为第一页,则为''
  • page.next 后一页页码,如果为最后一页,则为0
  • page.next_link 后一页URL,如果为最后一页,则为''
  • page.path 当前页网址(不含根路径),通常在主题中使用url_for(page.path)

归档页(archive)index布局相同,但是新增如下变量:

  • archive 为true
  • year 归档年份(4位)
  • month 归档月份(不包含0)

分类页(category)index布局相同,但是新增如下变量:

  • category 分类名称

标签页(tag)index布局相同,但是新增如下变量:

  • tag 标签名称

5、帮助函数

帮助函数被用于在模版中快速插入内容。

(1)URL

  1. url_for 返回一个带root路径的url,用法:<%- url_for(path) %>
  2. relative_url 返回from相对的to路径,用法:<%- relative_url(from, to) %>
  3. gravatar 插入Gravatar图片,用法:<%- gravatar(email, [size])%>,例如:

    <%- gravatar('a@abc.com') %>
    // http://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787
    <%- gravatar('a@abc.com', 40) %>
    // http://www.gravatar.com/avatar/b9b00e66c6b8a70f88c73cb6bdb06787?s=40
    

(2)HTML

  1. css 载入CSS文件。用法:<%- css(path, ...)%>path可以是数据或者字符串,如果path开头不是/或任何协议,则会自动加上根路劲;如果后面没有加上.css扩展名的话,也会自动加上。示例如下:

    <%- css('style.css') %>
    // <link rel="stylesheet" href="/style.css" type="text/css">
    
    
    <%- css(['style.css', 'screen.css']) %>
    // <link rel="stylesheet" href="/style.css" type="text/css">
    // <link rel="stylesheet" href="/screen.css" type="text/css">
    
  2. js 载入 JavaScript 文件。用法:<%- js(path, ...) %>path 可以是数组或字符串,如果 path 开头不是 /或任何协议,则会自动加上根路径;如果后面没有加上 .js扩展名的话,也会自动加上。

    <%- js('script.js') %>
    // <script type="text/javascript" src="/script.js"></script>
    <%- js(['script.js', 'gallery.js']) %>
    // <script type="text/javascript" src="/script.js"></script>
    // <script type="text/javascript" src="/gallery.js"></script>
    
  3. link_to 插入链接。用法:<%- link_to(path, [text], [options]) %>options参数有:

    • external 在新窗口中打开链接,默认值为false
    • class Class名称,也就是html标签a的class名
    • id ID名,也就是html标签a的id名

    示例如下:

    <%- link_to('http://www.google.com') %>
    // <a href="http://www.google.com" title="http://www.google.com">http://www.google.com</a>
    
    
    <%- link_to('http://www.google.com', 'Google') %>
    // <a href="http://www.google.com" title="Google">Google</a>
    
    
    <%- link_to('http://www.google.com', 'Google', {external: true, class: "link"}) %>
    // <a href="http://www.google.com" title="Google" target="_blank" rel="external" class="link">Google</a>
    
  4. mail_to 插入电子邮件链接。用法:<%- mail_to(path, [text], [options])%>options参数有:

    • class Class名称,也就是html标签a的class名
    • id ID名,也就是html标签a的id名
    • subject 邮件主题
    • cc 抄送(CC)
    • bcc 密送(BCC)
    • body 邮件内容

    示例如下:

    <%- mail_to('a@abc.com') %>
    // <a href="mailto:a@abc.com" title="a@abc.com">a@abc.com</a>
    
    
    <%- mail_to('a@abc.com', 'Email') %>
    // <a href="mailto:a@abc.com" title="Email">Email</a>    
    
  5. image_tag 插入图片。用法:<%- image_tag(path, [options]) %>options参数有:

    • class Class名称,也就是html标签a的class名
    • id ID名,也就是html标签a的id名
    • alt 替代文字
    • width 宽度
    • height 高度

    基本上就是img标签里的属性值。

  6. favicon_tag 插入favicon。用法:<%- favicon_tag(path) %>

  7. feed_tag 插入feed链接。用法:<%- feed_tag(path, [options]) %>,参数有:titletype(默认值为atom)

(3)条件函数

  • is_current 判断path是否符合目前页面的网址。<%- is_current(path, [strict]) %>
  • is_home 判断目前是否为首页。
  • is_post 检查目前是否为文章。 <%- is_post() %>
  • is_archive 检查目前是否为存档页面。<%- is_archive() %>
  • is_year 检查目前是否为年度归档页面。<%- is_year() %>
  • is_month检查目前是否为月度归档页面。<%- is_month() %>
  • is_category检查目前是否为分类归档页面。<%- is_category() %>
  • is_tag检查目前是否为标签归档页面。<%- is_tag() %>

(4)字符串处理

  • trim 清除字符串开头和结尾的空格。<%- trim(string) %>
  • strip_html 清除字符串中的 HTML 标签。<%- strip_html(string) %>,示例:

    <%- strip_html('It's not <b>important</b> anymore!') %>
    // It's not important anymore!
    
  • titlecase 把字符串转换为正确的 Title case。<%- titlecase(string) %> 示例:

    <%- titlecase('this is an apple') %>
    # This is an Apple
    
  • markdown 使用 Markdown 解析字符串。<%- markdown(str) %> 示例:

    <%- markdown('make me **strong**') %>
    // make me <strong>strong</strong>
    
  • render 解析字符串。<%- render(str, engine, [options]) %>

  • word_wrap使每行的字符串长度不超过 lengthlength 预设为 80。<%- word_wrap(str, [length]) %>,示例:

    <%- word_wrap('Once upon a time', 8) %>
    // Once upon\n a time
    
  • truncate移除超过 length 长度的字符串。<%- truncate(text, length) %> 示例:

    <%- truncate('Once upon a time in a world far far away', 16) %>
    // Once upon a time
    

(5)模板

  • partial载入其他模板文件,您可在 locals 设定区域变量。<%- partial(layout, [locals], [options]) %>

    参数 | 描述 | 默认值 --- | --- | --- cache | 缓存(使用 Fragment cache) | false only | 限制局部变量。在模板中只能使用 locals 中设定的变量。 | false

  • fragment_cache局部缓存。它储存局部内容,下次使用时就能直接使用缓存。<%- fragment_cache(id, fn); 示例:

    <%- fragment_cache('header', function(){
          return '<header></header>';
    }) %>
    

(6)日期与时间

  • date 插入格式化的日期。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js] 对象。format 默认为 date_format 配置信息。<%- date(date, [format]) %> 示例:

    <%- date(Date.now()) %>
    // Jan 1, 2013
    
    
    <%- date(Date.now(), 'YYYY/M/D') %>
    // 2013/1/1
    
  • date_xml插入 XML 格式的日期。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js] 对象。<%- date_xml(date) %> ,示例:

    <%- date_xml(Date.now()) %>
    // 2013-01-01T00:00:00.000Z
    
  • time 插入格式化的时间。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js] 对象。format 默认为 time_format 配置信息。<%- time(date, [format]) %> 示例:

    <%- time(Date.now()) %>
    // 13:05:12
    
    
    <%- time(Date.now(), 'h:mm:ss a') %>
    // 1:05:12 pm
    
  • full_date插入格式化的日期和时间。date 可以是 UNIX 时间、ISO 字符串、Date 对象或 [Moment.js] 对象。format 默认为 time_format 配置信息。 <%- full_date(date, [format]) %> 示例:

    <%- full_date(new Date()) %>
    // Jan 1, 2013 0:00:00
    
    
    <%- full_date(new Date(), 'dddd, MMMM Do YYYY, h:mm:ss a') %>
    // Tuesday, January 1st 2013, 12:00:00 am
    

(7)列表

  • list_categories 插入分类列表。<%- list_categories([categories], [options]) %>

    参数 | 描述 | 默认值 --- | --- | --- orderby | 分类排列方式 | name order | 分类排列顺序。1, asc 升序;-1, desc 降序。 | 1 show_count | 显示每个分类的文章总数 | true style | 分类列表的显示方式。使用 list 以无序列表(unordered list)方式显示。 | list separator | 分类间的分隔符号。只有在 style 不是 list 时有用。 | , depth | 要显示的分类层级。0 显示所有层级的分类;-10 很类似,但是显示不分层 级;1 只显示第一层的分类。 | 0 class | 分类列表的 class 名称。 | category transform | 改变分类名称显示方法的函数 |

  • list_tags 插入标签列表。<%- list_tags([tags], [options]) %>

    选项 | 描述 | 预设值 --- | --- | --- orderby | 标签排列方式 | name order | 标签排列顺序。1, asc 升序;-1, desc 降序。 | 1 show_count | 显示每个标签的文章总数 | true style | 标签列表的显示方式。使用 list 以无序列表(unordered list)方式显示。 | list separator | 标签间的分隔符号。只有在 style 不是 list 时有用。 | , class | 标签列表的 class 名称。 | tag transform | 改变标签名称显示方法的函数 | amount | 要显示的标签数量(0 = 无限制) | 0

  • list_archives 插入归档列表。<%- list_archives([options]) %>

    参数 | 描述 | 默认值 --- | --- | --- type | 类型。此设定可为 yearlymonthly。 | monthly order | 排列顺序。1, asc 升序;-1, desc 降序。 | 1 show_count | 显示每个归档的文章总数 | true format | 日期格式 | MMMM YYYY style | 归档列表的显示方式。使用 list 以无序列表(unordered list)方式显示。 | list separator | 归档间的分隔符号。只有在 style 不是 list 时有用。 | , class | 归档列表的 class 名称。 | archive transform | 改变归档名称显示方法的函数 |

  • list_posts 插入文章列表。<%- list_posts([options]) %>

    参数 | 描述 | 默认值 --- | --- | --- orderby | 文章排列方式 | date order | 文章排列顺序。1, asc 升序;-1, desc 降序。 | -1 style | 文章列表的显示方式。使用 list 以无序列表(unordered list)方式显示。 | list separator | 文章间的分隔符号。只有在 style 不是 list 时有用。 | , class | 文章列表的 class 名称。 | post amount | 要显示的文章数量(0 = 无限制) | 6 transform | 改变文章名称显示方法的函数 |

  • tagcloud 插入标签云。<%- tagcloud([tags], [options]) %>

    参数 | 描述 | 默认值 --- | --- | --- min_font | 最小字体尺寸 | 10 max_font | 最大字体尺寸 | 20 unit | 字体尺寸的单位 | px amount | 标签总量 | 40 orderby | 标签排列方式 | name order | 标签排列顺序。1, sac 升序;-1, desc 降序 | 1 color | 使用颜色 | false start_color | 开始的颜色。您可使用十六进位值(#b700ff),rgba(rgba(183, 0, 255, 1)),hsla(hsla(283, 100%, 50%, 1))或 [颜色关键字]。此变量仅在 color 参数开启时才有用。 | end_color | 结束的颜色。您可使用十六进位值(#b700ff),rgba(rgba(183, 0, 255, 1)),hsla(hsla(283, 100%, 50%, 1))或 [颜色关键字]。此变量仅在 color 参数开启时才有用。 |

(8)其他

  • paginator 插入分页链接。<%- paginator(options) %>

    参数 | 描述 | 默认值 --- | --- | --- base | 基础网址 | / format | 网址格式 | page/%d/ total | 分页总数 | 1 current | 目前页数 | 0 prev_text | 上一页链接的文字。仅在 prev_next 设定开启时才有用。 | Prev next_text | 下一页链接的文字。仅在 prev_next 设定开启时才有用。 | Next space | 空白文字 | &hellp; prev_next | 显示上一页和下一页的链接 | true end_size | 显示于两侧的页数 | 1 mid_size | 显示于中间的页数 | 2 show_all | 显示所有页数。如果开启此参数的话,end_sizemid_size 就没用了。 | false

  • search_form 插入 Google 搜索框。<%- search_form(options) %>

    参数 | 描述 | 默认值 --- | --- | --- class | 表单的 class name | search-form text | 搜索提示文字 | Search button | 显示搜索按钮。此参数可为布尔值(boolean)或字符串,当设定是字符串的时候,即为搜索按钮的文字。 | false

  • number_format 格式化数字。<%- number_format(number, [options]) %>

    参数 | 描述 | 默认值 --- | --- | --- precision | 数字精度。此选项可为 false 或非负整数。 | false delimiter | 千位数分隔符号 | , separator | 整数和小数之间的分隔符号 | .

    示例:

    <%- number_format(12345.67, {precision: 1}) %>
    // 12,345.68
    
    
    <%- number_format(12345.67, {precision: 4}) %>
    // 12,345.6700
    
    
    <%- number_format(12345.67, {precision: 0}) %>
    // 12,345
    
    
    <%- number_format(12345.67, {delimiter: ''}) %>
    // 12345.67
    
    
    <%- number_format(12345.67, {separator: '/'}) %>
    // 12,345/67
    
  • open_graph 插入 open graph 资源。<%- open_graph([options]) %>

    参数 | 描述 | 默认值 --- | --- | --- title | 页面标题 (og:title) | page.title type | 页面类型 (og:type) | blog url | 页面网址 (og:url) | url image | 页面图片 (og:image) | 内容中的图片 site_name | 网站名称 (og:site_name) | config.title description | 页面描述 (og:desription) | 内容摘要或前 200 字 twitter_card | Twitter 卡片类型 (twitter:card) | summary twitter_id | Twitter ID (twitter:creator) | twitter_site | Twitter 网站 (twitter:site) | google_plus | Google+ 个人资料链接 | fb_admins | Facebook 管理者 ID | fb_app_id | Facebook 应用程序 ID |

  • toc 解析内容中的标题标签 (h1~h6) 并插入目录。<%- toc(str, [options]) %>

    参数 | 描述 | 默认值 --- | --- | --- class | Class 名称 | toc list_number | 显示编号 | true

    下面示例就是解析文章内容,并生成目录列表:

    <%- toc(page.content) %>
    

6、本地化

所谓的本地化功能,就是在主题中设置不同的语言模版,在文件夹languages,然后通过设置改变网页中的预设文本。在模版中是通过___p来引用的。

例如你在_config.yml中设置language: zh-CN,而网页模版中有这么一段引用:<h1 class="title"><%= __('comment') %></h1>,那么网站会在languages文件夹中找zh-CH.yml文件,并找到对应的comment值,将值显示在网站中。

这一块知道这些就基本上满足了自定义主题的需求了。

7、插件

这一块内容主要针对开发者的,帮助开发hexo的插件或者向hexo提供插件,主要就是通过github提交代码。大致可以了解一下Hexo的九种插件,您可以在 API 页面中获得更多信息:

  • Generator
  • Renderer
  • Helper
  • Deployer
  • Processor
  • Tag
  • Console
  • Migrator
  • Filter

注意

1、上面提到的所有Options参数一定要按照json的格式来书写;
2、虽然官方Docs已经写得很详细了,但是缺乏实际例子,后续我会以我的站点为例,详细介绍一些功能如何使用。 或者直接在Github中fork我的主题light-ch(基于hexo-theme-light主题的China版)自行查看代码。

转载保存:Hexo | LP's Blog