Hexo 主题 Amber 开发与使用指南

时间  2019-11-15
标签 hexo 主题 amber 开发 使用 指南 繁體版
原文   原文链接

本文同步发布在 Easy Hexo 👨‍💻javascript

Amber 主题地址css

🎉 基于 Bootstrap + Vue 诞生的一款 Hexo 单页主题。html

Amber 主题演示

amber

在线演示：前端

Mitscherlich's Blogvue

下载 Amber 主题

  1. 进入 Github，直接下载默认分支；

amber

  1. 将下载的文件解压并将获得的文件夹重命名为 amber；html5

  2. 将这个文件夹放到你的博客根目录下的 themes 文件夹下。java

amber

若是你熟悉 git 的使用，能够直接克隆源码仓库：jquery

$ cd /path/to/your/blog # 进入你的博客地址
$ cd themes             # 进入 `themes` 文件夹
$ git clone --depth 1 https://github.com/Mitscherlich/hexo-theme-amber.git amber # 克隆主题
复制代码

启用 Amber 主题

很是简单，只须要在博客根目录下的 _config.yml 文件中将主题选项配置为 amber:webpack

# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: amber
复制代码

你能够在本地运行你的博客，或者从新生成它：git

$ hexo clean && hexo s # 本地运行你的博客
# 或者从新生成它！
$ hexo clean && hexo g && hexo s -s # 这只会展现生成的静态文件
# 或者你偏心 `serve` 也行！
$ serve public -p 8080
复制代码

如今，在你的浏览器中访问 http://localhost:8080，看看有什么变化？

配置 Amber 主题

TIP
在这一小节，没有特殊说明的状况下，_config.yml 指代的是 themes/amber 目录下的 _config.yml 文件，<root>/_config.yml 代指的是博客根目录下的 _config.yml 文件。

经过编辑 themes/amber 目录下的 _config.yml 文件来配置你的主题。如下全部的例子中的代码均可以在个人博客中找到。

基本配置

导航条

找到 _config.yml 中的 menu 字段，你能够很方便的定制你的导航条：

menu:
 home: /                 # 首页
 archives: /archives     # 归档页
  # 补充你的自定义菜单
  # 末尾的 `/index.html` 视状况能够省略
  # 示例:
  # [O] About: /about/index (若是你的页面是 `sources/<dir>/index.md` 的形式)
  # [O] About: /about (若是你的页面是 `sources/page.md` 的形式)
复制代码

因为这个主题是使用 vue 进行开发的，hexo 提供的 layout 功能无法用了，这可能为你定制本身想要的页面带来了一些麻烦；但好消息是，直接在 md 文件中书写 html 也是能够接受的，但若是你须要用到博客数据或者自定义更复杂的功能，请参考高级玩家 - 自定义页面这一小节，有两个详细的示例供你参考。

一个可行的例子是：

menu:
 Essay: /related/category/essay  # 找到全部分类为 essay 的文章
 Tech: /related/category/tech    # 找到全部分类为 tech 的文章
 Note: /related/category/note    # 找到全部分类为 note 的文章
 ACG: /related/tag/ACG           # 找到全部标签含有 ACG 的文章
  Node.js: /related/tag/Node-js   # 找到全部标签含有 Node.js/Node-js 的文章
 Python: /related/tag/Python     # 找到全部标签含有 Python 的文章
 Archives: /archives             # 归档页面
 pages:                          # 不支持二级菜单，层级导航将被展平
 - text: Projects              # 一个自定义页面
 link: /projects
 - text: Messages              # 另外一个自定义页面
 link: /messages
 - text: Donate                # 又一个自定义页面
 link: /donate
 - text: Profile               # 仍是自定义页面
 link: /profile
复制代码

RSS/Atom 订阅连接

若是你安装并配置了 hexo-generator-feed，你能够开启这一项为你的博客添加 RSS 订阅。在 _config.yml 里找到 rss 字段，一个可行的例子是：

rss:
 enable: true
 path: /api/atom.xml
复制代码

path 是你的 hexo-generator-feed 生成的文件能被访问到的绝对路径，若是你的博客在二级路径下，请在前面补充你的二级路径，由于这里的跳转不会被 vue-router 拦截到。

社交连接

这个配置影响边栏中的 Elsewhere (友言) 小控件。在 _config.yml 中找到 social 字段，它接受如下几项配置：

social:
  # facebook: ...
  # github: ...
  # twitter: ...
  # weibo: ...
 websites:
    # - text: ...
    # link: ...
复制代码

其中，facebook、github、twitter、weibo 字段有本身的 font-awesome 小图标，而 websites 字段能够做为友链使用，text 字段表示你想要显示的文本内容，

一个可行的例子是：

social:
 github: https://github.com/Mitscherlich
 weibo: https://weibo.com/Mitscherlich
 websites:
 - text: YUOSC
 link: https://yuosc.club
 - text: EasyHexo
 link: https://easyhexo.github.io/Easy-Hexo/
复制代码

侧边栏

侧边栏中简单的配置都放在这里。在 _config.yml 中找到 sidebar 字段，它接受如下几项配置：

## Sidebar
sidebar:
 leaf: To descript your blog. *Markdown* supported.
 github: Mitscherlich
复制代码

其中，leaf 影响小控件 Leaf 的内容，可使用 markdown 语法书写，文字内容将被渲染后显示在首页上； github 条目是可选的，用来展现博客做者的 Github 名片，若是留空，默认将会使用 <root>/_config.yml 中的 author 字段。

评论系统

如今支持的评论系统有：Gitalk、Gitment 和 Valine，在 _config.yml 中找到 comments 字段，它接受如下几项配置：

comments:
 enable: true
 engine: gitalk|gitment|valine # 请只保留你须要启用的评论系统！
复制代码

而后，为你的评论系统书写配置，注意 ⚠️，请务必缩进在 comments 字段下，配置将配自动加载：

例如，gitalk 接受如下几项配置：

comments:
 enable: true
 engine: gitalk
 gitalk:
    # 必须: github application client id
 clientID: process.env.clientId
    # 必须: github application client secret
 clientSecret: process.env.clientSecret
 repo: process.env.repo    # 必须: github repo
 owner: process.env.author # 必须: github repo owner
 admin:
 - process.env.author  # 必须: gitHub repo owner and collaborators
                            # only these guys can initialize github issues
复制代码

或者 gitment:

comments:
 enable: true
 engine: gitalk
 gitment:
 repo: process.env.repo    # 必须: github repo
 owner: process.env.author # 必须: github repo owner
 oauth:
      # 必须: github application client id
 client_id: process.env.clientId
      # 必须: github application client secret
 client_secret: process.env.clientSecret
复制代码

或者 valine:

comments:
 enable: true
 engine: gitalk
 valine:
    # 必须: leancloud app id
 appId: process.env.appId
    # 必须: leancloud app key
 appKey: process.env.appKey
复制代码

关于 valine 的使用，请参考其官网教程，正确填写 Leancloud 相关配置。

你可能注意到了，上面的配置中包含有大量 process.env.* 相似的文字，yaml 的语法并不容许从控制台读取环境变量，这意味着你必须将上述配置直接书写在 _config.yml 中，若是你介意在你的公开代码中暴露这些私有变量，你能够参考高级玩家 - 安全变量一节来了解如何私有化你的配置。

页脚信息

在页脚显示做者的我的连接和相关信息，在 _config.yml 中找到 powered_by 字段，一个可行的例子是：

powered_by:
 author: Mitscherlich
 link: https://github.com/Mitscherlich
复制代码

Google Analytics

google_analytics:
 enable: true
 track_id: UA-xxxxxxxxx-x
复制代码

开启后，将启用 Google Analytics 统计服务。

没有暴露配置的插件

fancybox

主题集成了 fancybox 用于展现图片幻灯，若是你不须要，请参考高级玩家 - 开启/关闭可选功能一节了解更多。

dplayer

主题集成了 dplayer 视频播放器，若是你不须要，请参考高级玩家 - 开启/关闭可选功能一节了解更多。

katex

主题集成了 katex 用于渲染公式，若是你不须要，请参考高级玩家 - 开启/关闭可选功能一节了解更多。

高级玩家

若是上面的基本配置还知足不了你，那么欢迎你进入“高玩”的地带，这里将告诉你如何更深刻的配置 Amber 主题，并将带你了解如何自定义这个主题。

注意 ⚠️
进入这一小节，我将默认你有必定的 html/css/js 基础，熟悉 git 基本命令的使用，而且了解过 vue.js 开发相关知识。
若是你还没准备好，我推荐你先去菜鸟教程阅读 html5 和 git 相关知识后再继续。

首先你要作的事情，就是从 develop 分支从新拉取主题代码，预编译的代码已经派不上用场了：

$ cd /path/to/your/blog
$ git clone -b develop --depth=1 https://github.com/Mitscherlich/hexo-theme-amber.git themes/amber
# 或者你不想覆盖已有主题，能够拉取到 themes/amber-dev 目录下
$ cd themes/amber # 或者 themes/amber-dev，视你上一步的结果而定
$ yarn install    # npm 也能够！但推荐使用 yarn！
复制代码

若是你将主题下载到了 themes/amber-dev 目录下，你还须要在 <root>/_config.yml 中将 theme 字段修改成 amber-dev

这一步完成后，你的目录结构应该跟个人同样：

amber

红框中的文件你是须要关注的部分你就说哪里不须要吧

开启/关闭可选功能

fancybox

fancybox 是一个 jquery 插件，你能够经过这样的形式在 md 文件中快速插入 fancybox：

{% fancybox slug /path/to/image [/path/to/thumbnail] [class] [title] %}
复制代码

例如：

{% fancybox esayhexo /assets/easyhexo/amber/preview.png Amber 主题示例图 %}
复制代码

渲染获得的结果：

<p>
  <a data-fancybox="gallery" href="/assets/easyhexo/amber/preview.png" title="Amber 主题示例图">
    <img class="" src="/assets/easyhexo/amber/preview.png" alt="Amber 主题示例图">
  </a>
</p>
复制代码

若是你用不到 fancybox，而且想要提高加载速度，你可选择仅用它。fancybox 并不没有被集成在 vue 工程中，而是直接在 vue 模版中被引用。在 public 目录下找到 index.html：

amber

图中标注的区域就是引入 jquery 和 fancybox 的代码，若是不须要，直接注释掉就好：

amber

完成后，你不能在代码中继续使用 fancybox 了，但 fancybox tag 还有效，在哪里找？

amber

这个文件负责在 hexo 中引入 fancybox tag，将它备份到一个不一样于 scripts 的目录就好：

$ mv scripts/tags/fancybox.js /path/to/backup.d/
复制代码

dplayer

DPlayer 是 b站 前端大佬 @DIYGod 的开源视频播放器（现一样用于 b站 播放页），支持懒加载、缩略图、弹幕等功能，你能够经过这样的形式在 md 文件中使用它：

{% dplayer key=value ... %}
复制代码

示例：

{% dplayer src=/assets/easyhexo/how-to-use-amber/install.mp4 %}
复制代码

渲染出来的结果：

<!-- dplayer counter starts with 0 -->
<div id="dplayer0" class="dplayer hexo-tag-dplayer-mark" style="margin-bottom: 20px;">
  <script> (function(){let player = {/* configs */};window.dplayers||(window.dplayers=[]);window.dplayers.push(player);})(); </script>
</div>
复制代码

一个例子的效果：

amber

若是你不想使用 dplayer，一样的，将它备份到一个不一样的目录就好：

$ mv scripts/tags/dplayer.js /path/to/backup.d/
复制代码

另外，若是你不想让 dplayer 出如今你的构建中，你还须要在这两个位置移除 dplayer 的引用，别担忧，虽然接下来涉及到一点点 Vue.js 和 TypeScript，但你彻底能够跳过这一步，由于文章中没有出现 dplayer 的话，它将不会被渲染，天然也不会影响到代码性能。

首先，你须要在 src/components/partials 下找到 Gallery.vue 这个文件：

amber

而后注释掉 renderDplayer：

amber

接下来在 src/pages/articles 下找到 _slug.vue 这个文件：

amber

一样的，注释掉 renderDplayer：

amber

就是这样！不管如何 dplayer 都不会被加载了！请容许我向 @DIYGod 大佬表达真挚的歉意

katex

主题一样还集成了 KaTex 用于支持 LaTeX 公式。一样的，在上述两个文件中，你很容易就能找到 renderMathInElement 函数，将它们注释掉，katex 就不会再困扰你了！我很遗憾你放弃了这么多不错的功能

安全变量

注意 ⚠️
在这一小节，我将默认你了解 Linux/Unix 命令行的使用，而且已经正确配置了你的 CI/CD。

hexo 使用 .yml 文件书写配置，这意味着将 OAuth Client Id/Secret 等变量暴露在外，是否会不太安全？若是你跟我有相同的顾虑，那么我很是推荐你阅读这一小节，若绝不在乎的话，那好吧，跳过这一小节也影响不大。

在 Github 上托管代码基本意味着开放，尤为在须要与人协做时，你的一些似有配置可能被 CI/CD（持续集成/部署）所须要，这意味着未经加密的变量将对互联网上的每一个人都是可访问的，但咱们彻底能够经过技术手段将这点问题解决。一下我将以 TravisCI 为例，为 gitalk 和 github pages 配置安全变量。

首先，你须要在 TravisCI 中设置加密的安全变量：

amber

接着，在你的 .travis.yml 中添加如下内容：

before_script:
 - cd themes/amber # 要修改的是 `themes/amber` 下的 `_config.yml`，不是 `<root>/_config.yml`
 - sed -i "s|process.env.clientId|$OAUTH_CLIENT_ID|g" _config.yml
 - sed -i "s|process.env.clientSecret|$OAUTH_CLIENT_KEY|g" _config.yml
 - cd - # 回到 `<root>`
复制代码

若是你想要成功的构建发布到 github pages，再添加如下内容：

deploy:
 provider: pages
 local-dir: public
 skip_cleanup: true
 keep-history: true
 committer-from-gh: true
 github-token: $GITHUB_TOKEN
复制代码

Ok! 这样就完成了！

不过仍要指出，这样配置的“安全变量”仍然是伪安全变量，只是在 CI/CD 中对外不可见而已，最后仍然会出如今你的前端构建中，即便例如本主题使用了 webpack 等构建工具也无济于事，有心之人仍然能够找出你“加密”的这些变量。最后，送给你们 Leancloud 的忠告：

AppKey 是客户端中使用的 Key，理论上客户端中全部请求都不该被信任，默认应认为 AppKey 是泄露的 —— Leancloud

自定义边栏

注意 ⚠️
接下来两个小节是这篇教程中最“高级”的部分，须要你对 Vue.js 和 TypeScript 都有所掌握，而且最好能熟练使用 pug 模版语法。固然，这两个小节的代码都是通过验证的，若是你想直接依葫芦画瓢也不是不能够。

不能自定义的主题不是好主题 —— 沃兹基·硕德

看来你的胃口有够大，主题自带的小控件已经不能知足你了。那么就让咱们开始实践，编写一个阿里云广告小控件，为你的博客创收吧！

首先，在 src/components/sidebar/widgets 目录下新建 Ads.vue 文件：

amber

在 Ads.vue 文件书写页面框架：

<template>
  <p>placeholder</p>
</template>

<script lang="ts"> </script>

<style lang="stylus" scoped> </style>
复制代码

接着，在 template 里面书写如下内容：

<transition name="fade">
  <!-- b-carousel 是 bootstrap-vue 的内置组件 -->
  <b-carousel class="ads mb-4" indicators v-model="slide">
    <b-link v-for="({ text, image, link }, i) in ads" :key="`ads-${i}`" :href="link" target="_blank">
      <b-carousel-slide :img-src="image" style="height: 160px;"/>
    </b-link>
    <span class="dismiss cursor-pointer" @click="dismissAds">&times;</span>
    <span class="tips">{{ $t('ads') }}</span>
  </b-carousel>
</transition>
复制代码

若是你熟悉 pug，这样写更简洁：

<template lang="pug">
  transition(name="fade")
    b-carousel.ads.mb-4(indicators, :interval="interval", v-model="slide", v-if="!dismiss")
      b-link(v-for="({ text, image, link }, i) in ads", :key="`ads-${i}`", :href="link", target="_blank")
        b-carousel-slide(:img-src="image", style="height: 160px;")
      span.dismiss.cursor-pointer(@click="dismissAds") &times;
      span.tips {{ $t('ads') }}
</template>
复制代码

后面的模版代码将所有用 pug 书写

在 script 部分中添加如下内容：

import { Vue, Component, Prop } from 'vue-property-decorator';
import store from 'store';

@Component({ name: 'Ads' })
export default class Ads extends Vue {
  private slide: number = 0;
  private dismiss: boolean = false;

  @Prop({ type: Number, default: 10 * 1000 })
  private interval?: number;

  @Prop({ default: [] })
  private ads?: Array<{ text: string; image: string; link: string; }>;

  private beforeMount() {
    const now = Date.now();
    const last = store.get('ads_expire_date', now);
    if (now - last > 1) {
      store.set('dismiss_ads', false);
    }
    this.dismiss = store.get('dismiss_ads', false);
  }

  private dismissAds(e: any) {
    e.preventDefault();
    this.dismiss = true;
    store.set('dismiss_ads', true);
    const now = Date.now();
    const expired = 24 * 60 * 3600; // 1 day
    store.set('ads_expire_date', now + expired);
  }
}
复制代码

样式向来复杂，这里照抄就好：

@import "~@/common/stylus/variables"

.ads
  &:hover
    .dismiss
      display block
  span.dismiss
    z-index 99
    font-size 28px
    display none
    position absolute
    right .5rem
    top -0.5rem
    color color-muted
    &:hover
      color color-light
  span.tips
    position absolute
    padding .1rem .25rem
    right .5rem
    bottom .5rem
    color color-light
    border 1px solid color-light
    border-radius .25rem
    font-size 14px
复制代码

在上一级目录中的 Sidebar.vue 中引用你添加的小控件：

amber

别忘了在 Sidebar 上添加 getter：

class Sidebar extends Vue {
  ...
  private get ads() {
    // `data` 就是 `sources/_data` 下的文件内容，和 `hexo` 数据目录用法一致
    return this.$store.state.data.ads || [];
  }
  ...
}
复制代码

自定义页面

看完了自定义小控件，来试试更复杂的功能：自定义页面吧！在这个例子中，我将为你们展现如何编写一个独立页面，用于展现你的项目做品。

首先，在 src/pages 目录下添加 Projects.vue 文件并书写大体框架：

<template lang="pug">
  p placeholder
</template>

<script lang="ts"> </script>

<style lang="stylus" scoped> </style>
复制代码

在 template 中插入如下内容：

.projects
  transition(name="fade", mode="out-in")
    b-card-group.mb-4(columns, v-if="projects.length")
      b-card(:img-src="preview", :key="`project-${i}`", v-for="({ name, description, link, preview }, i) in projects")
        h4 {{ name }}
        p {{ description }}
        footer(slot="footer"): b-link.text-muted(:href="link")
          fa-icon.mr-2.text-success(:icon="['far', 'thumbs-up']")
          small {{ $t('visit') }}
    b-row.justify-content-center(v-else): loading.my-5(style="margin: 0 auto;")
复制代码

在 script 中插入如下内容：

import { Vue, Component } from 'vue-property-decorator';

@Component({ name: 'Projects' })
export default class Projects extends Vue {
  private get projects() {
    return this.$store.state.data.projects || [];
  }
}
复制代码

在 style 中插入如下内容：

.projects
  .card
    .card-img
      border-bottom-right-radius 0!important
      border-bottom-left-radius 0!important
复制代码

怎么样，是否是很是简单？最后页面样式以下：

amber

不要忘了将页面组件加入路由，在 src/router.ts 中插入如下内容：

amber

如今，从新编译你的主题文件，若是没有任何问题，那么恭喜你，大功告成！🎊

写在最后

你们在使用中有什么问题能够在评论区留言，我将尽量回复。也欢迎在 Github、知乎、掘金、B站、微博 等关注我，及时获取个人其余项目以及相关最新动态。

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程