Upgrade to 4.0

Use this guide for an existing Solitude 3.x blog. For a new blog, follow Installation. This checklist follows the official v3.0.20...v4.0.0 comparison. Back up the blog source and configuration before starting.

1. Update the theme

Use the same installation method as the existing blog:

npm install hexo-theme-solitude@4

git -C themes/solitude fetch --tags
git -C themes/solitude switch --detach v4.0.0

2. Merge the configuration

Start with a fresh copy of the Solitude 4 default configuration, as described in Installation, and merge your customized values into it. Do not overwrite the new file with an old 3.x configuration.

Review these new or changed entries:

page.links.async_threshold controls asynchronous friend-link rendering.
theme_color.nav_hover_text.light/dark controls navigation hover contrast.
search.ai.enable and search.ai.url add an external AI entry to local search.
right_menu.custom_list[].click should call Solitude.randomPost() or another public Solitude method.

3. Migrate custom JavaScript

Replace custom code that calls pjax.loadUrl, utils.getScript, utils.getCSS, GLOBAL_CONFIG, or PAGE_CONFIG with the public methods described in Browser API. Do not build integrations against internal globals such as sco, rm, ai, or coverColor.

In custom templates, use data-solitude-action with a function registered on window.Solitude instead of injecting inline event handlers.

4. Check CDN and self-hosting

The browser entry point is a native ES module. If Solitude's JavaScript is served from a CDN or another host, publish the complete source/js/ tree from one theme version and preserve its relative paths. Serving only main.js breaks its relative imports.

5. Clean, rebuild, and test

hexo clean
hexo generate
hexo server

Test repeated PJAX navigation through the homepage, a post, archives, links, and music. Also test enabled search and comment providers, theme switching, the context menu, custom templates, and browser back/forward navigation. If a check fails, continue with Troubleshooting.