hexo 学习►主题►landscape

Hexo 主题 Landscape 完全指南：从安装到个性化配置

欢迎来到 Hexo 主题 Landscape 的学习教程。Landscape 是 Hexo 官方默认的经典主题，它结构清晰、功能完备，非常适合作为初学者理解 Hexo 主题机制的入门案例。本文将带你从零开始，完成主题的安装、启用、配置以及核心功能的使用。

一、主题安装与启用

在 Hexo 5.0 及更高版本中，安装主题变得非常简单。你可以选择通过 npm 包管理器安装，或者通过 Git 克隆源码的方式安装。

1. 安装方式

方式 A：使用 npm 安装（推荐）

这是最简洁的方式，主题会被安装在 node_modules 目录下，便于统一管理。

1
npm i hexo-theme-landscape

方式 B：使用 Git 克隆

如果你希望直接修改主题源码或方便地切换分支，可以将主题克隆到 themes 目录。

1
git clone --depth 1 https://github.com/hexojs/hexo-theme-landscape themes/landscape
  • 参数说明：
    • --depth 1：这是一个 Git 参数，表示只下载最近的一次提交记录。这可以大幅减少下载体积，加快克隆速度，对于只需要使用稳定版主题的用户来说足够了。
    • https://...：主题的远程仓库地址。
    • themes/landscape：本地目标路径。这告诉 Git 将代码下载到博客根目录下的 themes 文件夹中，并重命名为 landscape。

额外依赖

如果你计划启用 RSS 订阅功能，还需要安装一个额外的插件：

1
npm install hexo-generator-feed

2. 启用主题

安装完成后，Hexo 还不知道要使用这个新主题。你需要修改博客根目录下的 _config.yml 文件。

找到 theme 这一行，将其值修改为 landscape。

1
2
3
4
5
6
7
# 博客根目录 _config.yml

# 修改前
theme: some-theme

# 修改后
theme: landscape
  • 概念辨析：这里的 theme 配置项指定了 Hexo 渲染网站时使用的主题文件夹名称。如果你用 npm 安装，文件夹名通常是 hexo-theme-landscape，但 Hexo 能自动识别简写 landscape；如果你用 Git 克隆到 themes/landscape，名字就是 landscape。

3. 主题更新

保持主题最新可以获取修复和新功能。

npm 用户更新命令：

1
npm install hexo-theme-landscape@latest
  • 参数说明：@latest 告诉 npm 明确安装该包的最新版本。

Git 用户更新命令：

1
2
cd themes/landscape
git pull
  • 命令组合说明：
    1. cd themes/landscape：切换当前工作目录到主题文件夹内部。
    2. git pull：从远程仓库拉取最新的代码并合并到本地。

二、核心配置策略：如何安全地自定义

这是初学者最容易踩坑的地方，请务必仔细阅读。

1. 配置文件的位置

Landscape 主题自带一个配置文件 _config.yml。

  • 如果是 npm 安装，它位于 node_modules/hexo-theme-landscape/_config.yml。
  • 如果是 Git 克隆，它位于 themes/landscape/_config.yml。

2. 为什么不要直接修改主题自带的 _config.yml？

想象一下，主题自带的配置文件是“出厂设置”。当你未来执行 git pull 或 npm update 更新主题时，这个文件会被新版本的文件完全覆盖。你辛辛苦苦做的修改瞬间就会消失。

3. 正确的做法：使用外部配置文件

Hexo 提供了一种机制，允许你在博客根目录下创建一个独立的配置文件来覆盖主题的设置。

操作步骤：

  1. 复制主题内的 _config.yml 到你的博客根目录。
  2. 将其重命名为 _config.landscape.yml。
    • 命名规则：格式必须是 _config.[主题名].yml。因为你的主题名叫 landscape，所以文件名必须是 _config.landscape.yml。
  3. 以后所有的主题修改，都只在这个新文件中进行的。

优先级比喻：
如果把配置过程比作穿衣服，主题自带的 _config.yml 是“内衣”，根目录的 _config.landscape.yml 是“外套”。Hexo 会优先展示“外套”上的图案（配置）。如果“外套”上没写某项设置，才会去参考“内衣”。这样既保留了原始设置，又实现了个性化，且更新主题时“外套”不会受影响。

三、核心功能配置详解

打开你刚刚创建的 _config.landscape.yml，我们将详细解读其中的关键配置项。

1. 侧边栏 (Sidebar)

侧边栏是博客的导航中心，你可以决定它显示在页面的哪个位置。

配置项： sidebar

1
2
3
# _config.landscape.yml

sidebar: right
  • 可选值：
    • left：侧边栏显示在页面左侧。
    • right：侧边栏显示在页面右侧（默认）。
    • bottom：侧边栏内容显示在页面底部。

内置小工具 (Widgets)：
Landscape 默认开启了 5 个实用的小工具，你可以在 widget 配置项中单独开启或关闭它们。

1
2
3
4
5
6
widget:
  - category    # 文章分类列表
  - tag         # 文章标签云
  - tagcloud    # 更炫酷的标签云展示
  - archives    # 文章归档列表
  - recent_posts # 最新文章列表
  • 操作说明：如果你想隐藏“分类”列表，只需在列表中删除 - category 或在前面加上 # 注释掉即可。

你可以在博客顶部的导航栏添加带有图标的社交媒体链接，方便读者关注你。

配置示例：

1
2
3
4
links:
  github: https://github.com/your_github_account
  twitter: https://twitter.com/your_twitter_account
  telegram: https://t.me/your_telegram_account
  • 配置逻辑：
    • 键名（如 github, twitter）：决定了显示什么图标。Landscape 内置了常见社交平台的图标映射。
    • 键值（URL）：点击图标后跳转的地址。
    • 你可以随意添加新的键值对，只要键名对应主题支持的图标名称即可。

3. 图片展示功能 (FancyBox)

Landscape 集成了 Fancybox，这是一个强大的lightbox插件。当用户点击文章中的图片时，图片会以弹窗形式放大展示，提供更好的浏览体验。

使用方法 A：标准 Markdown 语法

这是最简单的方式，Landscape 会自动识别并启用 Fancybox 效果。

1
![图片描述文字](图片链接地址)

使用方法 B：使用 Hexo 标签插件

如果你需要更精细的控制（例如指定缩略图），可以使用 Hexo 提供的 fancybox 标签。

1
{% fancybox 图片原图地址 [图片缩略图地址] [图片描述文字] %}
  • 参数详解：
    • 图片原图地址：必填。点击后弹出的大图地址。
    • [图片缩略图地址]：可选。如果在文章中想显示一张小图，点击后看大图，可以填这里。如果不填，则直接显示原图。
    • [图片描述文字]：可选。图片的标题或说明。

示例对比：

  1. 简单模式（自动适配）：

    1
    ![帮助文档截图](/images/help.png)

    帮助文档截图
    效果：文章显示该图片，点击后全屏放大。

  2. 高级模式（自定义缩略图）：

    1
    {% fancybox /o/hexo-learn/images/matrix.png /o/hexo-learn/images/matrix_thumb.png 黑客帝国代码雨 %}
    /o/hexo-learn/images/matrix.png 黑客帝国代码雨 /o/hexo-learn/images/matrix.png 黑客帝国代码雨

    效果：文章显示 matrix_thumb.png 这张小图，点击后弹出 matrix_full.png 这张大图，并显示标题“黑客帝国代码雨”。

四、常见问题与注意事项

  1. 关于菜单配置的补充说明：
    虽然本文主要介绍了侧边栏和链接，但在实际使用中，很多初学者会困惑于“菜单”配置。如果你在根目录 _config.yml 的 theme_config 中配置了 menu，又在 _config.landscape.yml 中配置了 menu，同时主题默认文件里也有 menu。

    • 原理：Hexo 的配置合并机制是“深度合并”。如果三个地方的菜单项键名（Key）不同（例如一个是 Home，一个是 首页，一个是 ahome），Hexo 会认为它们是三个不同的菜单项，从而全部显示出来，而不是互相覆盖。
    • 建议：为了保持菜单整洁，建议只在 _config.landscape.yml 中统一维护菜单配置，并确保键名的一致性，或者在不需要某些默认菜单时，在外部配置文件中显式地将其设为空或不配置。

  2. 图片路径问题：
    文中展示了如下图片引用：

    1
    2
    ![help](/images/help.png)
    ![matrix](/images/matrix.png)

    help
    matrix
    这里的 /images/ 通常指的是 Hexo 的 source/images/ 目录。请确保你已经将图片文件放入了博客源文件目录下的对应文件夹中，否则编译后会找不到图片（404错误）。

  3. 链接资源：

通过以上步骤，你应该已经成功安装并个性化了你的 Hexo Landscape 主题。记住，永远不要在主题源文件夹内直接修改配置，善用 _config.landscape.yml 是你成为 Hexo 高手的第一步。