After testing out a few different static site generators, I settled on Hexo to create this site. Hexo is incredibly simple and flexible and I like the fact that it doesn’t depend on anything other than good old Javascript, HTML and CSS (and of course Node for the build process.)
Content authoring is simple and very much like other static site generators. I just write Markdown posts in my favourite text editor, and let the build process generate static HTML pages.
The Problem: Limitations of the Hexo asset_img tag
I’m very happy with the Hexo experience overall, but there was one fly in the ointment that made editing and previewing my posts a bit fiddly, and that is that Hexo doesn’t support the Markdown format for adding images to a post, e.g:
1 |  |
Instead, in order to work with the Hexo build process, a custom tag is required:
1 | {% asset_img image-path.png Alt Text %} |
While this works fine when deploying to a site or previewing locally with hexo serve, it doesn’t play nicely with Markdown tools like the VS Code markdown preview, and so adds extra steps to the authoring workflow.
The Solution: Using standard Markdown syntax to add Hexo images
Thankfully, there is an NPM package available that remedies this issue and fits snugly into the Hexo build pipeline, works with Markdown tools and the local Hexo server.
The package is compatible with the Hexo per-post asset folder, so head over to your root _config.yml and ensure the following is set:
1 | post_asset_folder: true |
Then, in your terminal run
1 | npm i -s hexo-asset-link |
That’s it! No configuration required. So, if your image path is:
1 | ./source/_posts/Post-Asset-Folder/image-name.png |
You can simply use the Markdown syntax:
1 |  |
and it will show correctly in both the markdown preview, the Hexo local server, and when built on your site.
Happy writing!