Hexo资源文件夹

本文将介绍 Hexo 资源文件夹的使用,以及解决如何以相对路径的方式引用图片使其能够在主页和文章中正常显示。

Hexo资源文件夹

参考官方文档 Hexo

本文基于 hexo: 3.8.0

资源文件

资源(Asset)代表 source 文件夹中除了文章以外的所有文件,例如图片、CSS、JS 文件等。

直接引用

如果 Hexo 项目中只有少量图片,那最简单的方法就是将它们放在 source/images 文件夹中,然后通过以下方法引用:

1
![direct](/images/img.png)

编译成静态文件后 img.png 存放在 public/images 文件夹下,生成的 html 文件中的引用路径为:

1
<img src="/images/img.png" alt="direct">

使用文章资源文件夹

对于那些想要更有规律地提供图片和其他资源以及想要将他们的资源分布在各个文章上的人来说,Hexo 也提供了更组织化的方式来管理资源。这个功能可以通过将 _config.yml 文件中的 post_asset_folder 选项设为 true 来打开。

1
post_asset_folder: true

当资源文件管理功能打开后,Hexo 将会在你每一次通过 hexo new [layout] <title> 命令创建新文章时自动创建一个文件夹。这个资源文件夹与这个 markdown 文件同名。将所有与该文章有关的资源放在这个关联文件夹中之后,你可以通过相对路径来引用它们,推荐使用该方式,其引用方式和原生 Markdown 方式一致,避免过多的使用 Hexo 的扩展标签。

使用 post_asset_folder 存在的一些问题,可以参考下方 "图片的相对引用"。

使用标签插件

通过常规的 markdown 语法和相对路径来引用图片和其它资源可能会导致它们在存档页或者主页上显示不正确,你可以使用 标签插件 来解决这个问题。

1
{% asset_img slug [title] %}

例如,当你打开文章资源文件夹功能后,你把一个 example.jpg 图片放在了你的资源文件夹中,如果通过使用相对路径的常规 markdown 语法 ![](./example.jpg)![](example.jpg),它将不会出现在首页上,但它会在文章中正常显示。

通过下列方式,图片将会同时出现在文章和主页以及归档页中。

1
{% asset_img example.jpg This is an example image %}

图片的相对引用

开启 post_asset_folder 后,例如创建一篇名为 "assetsTest" 的文章并引用一张图片,它的文件目录结构如下:

1
2
3
4
5
$ tree source/_posts
source/_posts
├── assetsTest
│ └── example.png
└── assetsTest.md

三种相对引用的写法及其效果:

  • ![example](example.png)

    Hexo 官方文档关于 markdown 的示例写法,图片不能在主页正常显示,但在文章中能正常显示。此外,这种相对引用写法在绝大数 markdown 编辑器的预览视图中都无法正常显示图片(Typora 通过设置 Use Image Root Path 可以解决,它会在文件头添加 typora-root-url: xxxx)。

  • {% asset_img example.png example %}

    Hexo 官方推荐使用标签的写法,图片能在主页和文章中正常显示,但是不能在 markdown 编辑器的预览视图中预览图片。

  • ![example](assetsTest/example.png)

    几乎所有的 markdown 编辑器都支持的相对引用的写法,在markdown 编辑器的预览视图中都能正常显示图片,但在主页和文章中无法正常显示。

推荐使用第三种写法,为了解决无法在主页和文章中正常显示的问题,需要安装 hexo-asset-image 插件:

1
npm install hexo-asset-image@0.0.1 --save