Hexo 博客 Markdown 写作工作流

如何在本地预览和博客中都能正常显示图片?

图片调整大小

markdown中插入的图片是不支持调整大小的,最终在博客中展示出来的效果是按照原始分辨率尺寸展示的,但是会有一个最大宽度限制,也就是不超过正文部分的宽度。

如果想要博客最后呈现出来的图片是调整了大小的。可以在markdown文本中使用HTML的 <img> 标签,自己加上 width 等属性。

但是直接使用 img 标签还有一个问题,就是使用相对路径的话只会文章页面有作用,如果是在首页文章节选部分展示了图片,那么这个图片会因为URL问题显示不正常。Hexo 官方给的方案是基于 {% asset_img slug [title] %} 这种块标签,这样 Hexo 渲染的时候会自动处理好所有位置使用到的 URL。

由于官方的 asset_img 标签不支持宽度调整设置,所以基于这个标签的插件 hexo-asset-img 也不能让我满意。

官方的 asset_img 标签支持宽度调整设置

用法:

1
{% asset_img Engels_portrait_in_1877.jpg 宽度数值 %}

对应功能的源代码:

hexo/lib/plugins/tag/asset_img.ts at 439ee6d19ead7973048b61f896437c30803cf17a · hexojs/hexo

hexo/lib/plugins/tag/img.ts at 439ee6d19ead7973048b61f896437c30803cf17a · hexojs/hexo

实际采用的解析顺序:

1
{% asset_img [class names] slug [width] [height] [title text [alt text]] %}

也就是说可以指定 class、src、width、height、title、alt 这些属性。

The Image Embed element - HTML: HyperText Markup Language | MDN

HTML img(图片)元素中的 alt 属性与 title 属性区别

alt 与 title 属性区别:

图片中的 alt 属性是在图片不能正常显示时出现的文本提示。

图片中的 title 属性是在鼠标在移动到元素上的文本提示。

img alt 是什么?对于SEO来说很重要吗?

Image图片Alt标签SEO优化全面指南-内含示例解析 - 外贸老船长

hexo-image-link 这款插件做的是同样的事情,而且支持 img 标签,要更好用一些。

很好,这个插件很好用,因为支持 img 标签,所以可以做到同时在 Typora 中预览,以及最终的渲染,以及在所有页面的 URL 处理问题。

但是使用 img 仍然有一个缺点,就是当文章源文件修改名称的时候,文章中的 img 标签中的路径全都需要跟着改。而 asset_img 方式是不需要的,只需要保证 asset 文件夹和源文件保持一样,但是文章正文是不需要改任何东西的。

hexo-image-link 还有一些 BUG 或者缺点:

  1. 对于 img 标签的处理很简单,可能无法支持一些特殊属性。
  2. 对于 img 标签的处理,如果你的 permalink 格式是 xxx.html 结尾的,会导致无法正确处理路径。
  3. 日志打印的比较随意,hexo 构建的时候,日志很乱没有条理。
  4. 代码实现用的是正则表达式替换,不确定需要处理的文章很多的时候,性能如何。不过一般使用的话性能上没啥问题。

cocowool/hexo-image-link: 当MD中引用本地文件时,处理生成的html中的图片链接。

yiyungent/hexo-asset-img: 🍰 Hexo local image plugin. | Hexo 本地图片插件: 转换 图片相对路径 为 asset_img

@kur4ge/hexo-asset-path - npm

这个貌似也是来解决问题的,不过还没研究。

自己重新开发插件

由于 hexo-image-link 采用的是正则表达式处理 img 标签,用的方式很简单,对于很多细节并没有很好的处理,所以我重新开发了一下。

图片预览问题(打草稿过程中)

我目前(2018年12月-2019年1月)的博客URL方案。

打草稿时,使用Typora写作。如果直接使用 <img> 标签,

相关代码:

1
<img src="xxx.png" alt="xxx" width="300px">

另外,图片默认没有图注,如果想要图注,还得自己写 HTML 来实现。

居中显示的图注:

1
<p align="center">xxx</p>

这里《hexo + typora 图片插入解决办法 - Yumine - 博客园》有博主介绍了另外一种方法,Hexo 有一个功能,可以在粘贴图片到 Typora 中的时候,把图片复制到某个文件夹中,或者基于图床工具自动上传到图床。可以设置 hexo 的图片根目录,粘贴图片的时候自动把图片复制或者下载到对应目录。

Typora 还支持读取 Front-Matter,如果其中有 typora-root-url,那么会自动把这个属性配置的路径当作资源的根目录。

其他:

Hexo+Typora处理博客图片 - SFZhang

让 hexo 文章图片在 typora 里也能显示

Hexo + Chic + Typora如何实现便捷的文章插入图片方案?Hexo文章图片无法显示问题如何解决? | Myoontyee | Hi’CT & Robotic

Asset Folders | Hexo【这篇官方文档专门讲如何处理资源管理的,比如图片少的时候建议只用一个 images 文件夹,如果图片多或者希望把每个文章的图片单独一个文件夹管理应该怎么做】

还有一种不太完美,但是或许能用的方式,把 Typora 和浏览器窗口并列分屏,左边 Typora,右边是对应文章的预览。由于 Hexo 可以实时渲染,这样左边写一会儿,刷新一下右边看一下效果,就能看到左边看不到的图片了。

表格

粘贴与复制表格

直接从 Excel 复制到 Typora

从 Excel 复制内容,然后直接粘贴到 Typora 中,会自动转换为 Markdown 格式的表格。但是从 Excel 中复制数据,然后粘贴到 Typora 中已经存在的表格中,Typora 不会自动转换,只会粘贴从 Excel 复制的第一行。

缺点:表格中的内容有一些位置的一个空格会变成三个空格。

借助第三方工具

tableconvert

Markdown 表格中换行

使用 HTML 的 <br> 标签

排查错误

有时候可能忘记了为某些文章指定 urlname,这种情况如何排查呢。在本地执行 hexo g 之后,到根目录下的 public 文件夹下找找看有没有名字为 null 的文件夹,如果有,那么其中放的就是没有指定 urlname 的文章渲染出来的 HTML 文件。

_posts 文件夹中文件太多怎么办

文章太多都放在一个文件,找起来也不方便。

其实可以在 _posts 问价夹下建立分类文件夹,比如所有写 LeetCode 的文章都放 LeetCode 文件夹下。

如果有使用到图片的文章,只需要把图片放在和文件名完全相同的文件夹中,然后把这个文件夹和文件放在同一个目录下即可。这样,执行 hexo generate 生成网站静态文件的时候,Hexo 会自动把和文章同名的文件夹中的文件(比如图片)放到文件所在的目录中。这个是基于 hexo 的 Asset 文件夹机制实现的,参考Asset Folders | Hexo

注意:文章必须和 Asset 目录在同级目录,不能把文章放到 Asset 文件夹中,不然 Asset 功能会失效。

已经实际测试过,虽然是放在子文件夹中,但是渲染之后,hexo 会为每篇文章在 public 文件夹中建立唯一的一个文件夹,也就是说,虽然在 _posts 中是有层级结构的,但是渲染之后实际上是看不出来层级结构的。在 _posts 中建立文件夹只是方便我们更好地管理文章。

如何做到文章和资源放在同一个目录?

实现 hexo 文章和资源在同一目录下 - Hunsh’s Blog

hexo-asset-dir - npm

How to put post Markdown file into asset folder? · Issue #3245 · hexojs/hexo

当 urlname 中有大写字母时候怎么办?

urlname 中有大写字母,一般访问的时候都会自动跳转为纯小写的路径,可能会影响 SEO,所以打算在构建的时候提醒一下这种情况。

参考资料

  1. Hexo常见问题解决方案