hexo-recover: rebuild the Markdown sources from a generated Hexo site, then verify the rebuild

[Belyenochi]

Sharing a small tool for a situation I ended up in: I switched machines and the Hexo source/ folder never made it across — the Markdown was gone for good, while the blog itself was still online. All I had was the generated HTML in .deploy_git, so I wrote something to turn that back into the Hexo project.

hexo-recover rebuilds the Hexo project from that HTML — posts with front matter, images, and the site/theme config as far as the pages reveal it — and then lets you verify the result by rendering it back through Hexo and diffing every post body against the original.

npx hexo-recover recover ./my-site-html ./blog --url https://you.github.io
cd blog && npm install && npx hexo generate
npx hexo-recover verify ../my-site-html ./public

Repo: https://github.com/Belyenochi/hexo-recover · npm: https://www.npmjs.com/package/hexo-recover

What makes it different from a generic HTML→Markdown converter is that it knows Hexo's exact output shapes: the line-numbered figure.highlight code tables, headerlink anchors inside headings, headings and hard breaks inside list items, indented vs fenced code, and the CommonMark emphasis rules that current marked enforces but older versions did not. Each rule is pinned by a test, and each one came from a real difference found by the verify step.

Supported themes (v0.2.0, detected automatically): NexT, Butterfly, Fluid, Icarus, Volantis, Stellar, Keep, Redefine and Landscape. Each preset was read from a site generated with the theme's current release; those sites are fixtures in the repo, and the tests recover each one, compare the posts to the source Markdown, and run verify against the NexT rendering of the same posts. Title, dates and tags come from the Open Graph tags Hexo writes into every page, so they do not depend on the theme at all; the theme-specific parts are the body container, category links, index excerpts, menu and avatar. For a theme not on the list, --body-selector pointing at the article body is enough to get the posts back.

Results on the site I recovered (25 posts, NexT 5.1.4 originally, rebuilt on Hexo 8 + NexT 8): every post identical to the original once whitespace is ignored, zero structural differences.

Current limits: the theme config written out is always NexT 8's — menu, avatar and social links read from another theme are carried over into it. Themes that show only the day of a post (Butterfly, Icarus, Landscape) get the exact UTC instant in the front matter rather than a local time. Posts are located by the YYYY/MM/DD/slug/ permalink unless you pass --post-glob. verify does not run Hexo for you.

If your site uses a theme not listed above, a post page and the index page are all that is needed to add a preset.

[Belyenochi]

Update — v0.2.0 adds presets for eight more themes, with auto-detection.

Butterfly, Fluid, Icarus, Volantis, Stellar, Keep, Redefine and Landscape now work out of the box next to NexT; --theme is no longer needed.

How they were added, since it may be useful to others working with generated Hexo sites: I built one small site per theme with Hexo 8 and the theme's current release, and read the selectors from the real output. Those sites are in the repo as fixtures, and the tests recover each one, compare the posts to the source Markdown, and run verify against the NexT rendering of the same posts.

Two things I did not expect:

• The article body is byte-for-byte the same across all nine themes — it is hexo-renderer-marked output, the theme only wraps it. The one exception was Fluid's code blocks (no span.line, lines separated by <br>).
• Title, dates and tags can be read from the Open Graph tags Hexo's open_graph() helper writes into every page, so they are theme-independent too. The only theme-specific parts left are the body container, category links, index excerpts, menu and avatar.

Still looking for samples of themes not on the list: one post page plus the index page is enough to add a preset.