`permalink :title` changed without backward-compatible replacement

[dimaslanjaka]

Check List

• I have already read Docs page & Troubleshooting page.
• I have already searched existing issues and they are not help to me.
• I examined error or warning messages and it's difficult to solve.
• I am using the latest version of Hexo. (run hexo version to check)
• My Node.js is matched the required version.

Expected behavior

In the latest Hexo update, the :title permalink no longer matches the post's file path as it used to.
This change breaks existing post URLs for users who relied on the previous behavior, and there is currently no replacement option to maintain the old permalink structure.

This impacts blogs that have been live for years, causing broken links and SEO issues.
Please consider providing a backward-compatible replacement or a setting to restore the previous behavior.

Related discussion: https://github.com/orgs/hexojs/discussions/5630#discussioncomment-12904542

Actual behavior

Currently, the :title permalink is no longer based on the post's file name under source/_posts/.
Instead, it appears to be generated from the post-folder-post-filename, causing the permalink to differ from the expected file-based path.

How to reproduce?

1. install hexo etc
2. in _config.yml set permalink to :title.html

Is the problem still there under Safe mode?

Yes

Your Node.js & npm version

node v20.18.3
npm 11.2.0

Your Hexo and Plugin version

hexo-site@0.0.0 D:\Repositories\site
├── @isaacs/fs-minipass@4.0.1 extraneous
├── @npmcli/agent@3.0.0 extraneous
├── @types/keyv@3.1.4 extraneous
├── @types/node@22.15.3 extraneous
├── @types/responselike@1.0.3 extraneous
├── cheerio@1.0.0
├── eslint-config-hexo@6.0.0
├── eslint@9.25.1
├── exponential-backoff@3.1.2 extraneous
├── hexo-clean-css@2.0.0
├── hexo-filter-nofollow@2.0.2
├── hexo-fs@5.0.0
├── hexo-generator-archive@2.0.0
├── hexo-generator-feed@3.0.0
├── hexo-generator-sitemap@3.0.1
├── hexo-renderer-marked@7.0.1
├── hexo-renderers@3.0.0
├── hexo-server@3.0.0
├── hexo-tag-embed@1.0.0
├── hexo-uglify@2.0.0
├── hexo@7.3.0
├── husky@9.1.7
├── imagemin-lint-staged@0.5.1
├── lint-staged@15.5.1
├── lunr@2.3.9
├── node-gyp@11.2.0 extraneous
├── nopt@8.1.0 extraneous
├── npm-check-updates@18.0.1
├── proc-log@5.0.0 extraneous
├── sharp@0.34.1
├── tinyglobby@0.2.13 extraneous
└── undici-types@6.21.0 extraneous

Your package.json

{
  "name": "hexo-site",
  "version": "0.0.0",
  "private": true,
  "hexo": {
    "version": "7.3.0"
  },
  "scripts": {
    "build": "hexo generate",
    "eslint": "eslint .",
    "prepare": "husky install"
  },
  "dependencies": {
    "cheerio": "^1.0.0",
    "hexo": "^7.3.0",
    "hexo-clean-css": "^2.0.0",
    "hexo-filter-nofollow": "^2.0.2",
    "hexo-fs": "^5.0.0",
    "hexo-generator-archive": "^2.0.0",
    "hexo-generator-feed": "^3.0.0",
    "hexo-generator-sitemap": "^3.0.1",
    "hexo-renderer-marked": "^7.0.1",
    "hexo-renderers": "^3.0.0",
    "hexo-server": "^3.0.0",
    "hexo-tag-embed": "^1.0.0",
    "hexo-uglify": "^2.0.0",
    "lunr": "2.3.9",
    "sharp": "^0.34.1"
  },
  "devDependencies": {
    "eslint": "^9.25.1",
    "eslint-config-hexo": "^6.0.0",
    "husky": "^9.1.7",
    "imagemin-lint-staged": "^0.5.1",
    "lint-staged": "^15.5.1",
    "npm-check-updates": "^18.0.1"
  },
  "lint-staged": {
    "*.{png,jpeg,jpg,gif,svg}": [
      "imagemin-lint-staged",
      "git add"
    ],
    "*.js": "eslint --fix"
  },
  "engines": {
    "node": ">=14"
  },
  "packageManager": "yarn@4.9.1"
}

Your site's _config.yml (Optional)

title: Hexo
subtitle: "A fast, simple & powerful blog framework powered by Node.js."
description: "Hexo is a fast, simple & powerful blog framework powered by Node.js."
author: Hexo
language: en
timezone: UTC

url: https://www.webmanajemen.com/hexo-themes
root: /hexo-themes/
permalink: :title.html
archive_dir: archives
code_dir: downloads/code
new_post_name: :year/:month/:day/:title.md # File name of new posts
post_asset_folder: true
per_page: 0
pretty_urls:
  trailing_index: false
  trailing_html: false

theme: mundana

highlight:
  enable: true
  line_number: false

disqus_shortname: hexojs
google_analytics: UA-48498357-3
fb_admins: 100000247608790
algolia:
  en:
    api_key: c3d5d4c995b5e0c2ffb5623900279a66
    index_name: hexo
  zh-tw:
    api_key: c83d2ec3440f40aec6d0e695ecec7ef3
    index_name: hexo_zh-tw
  zh-cn:
    api_key: cdea7d4e47d84f6145b77e7f68689f35
    index_name: hexo_zh-cn
twitter: hexojs
github: hexojs/hexo

Others

No response

[dimaslanjaka]

@SukkaW @stevenjoezhang how this can be replaced without backward-compatibility ?

[KUNDAN1334]

@dimaslanjaka Can this issue be resolved by manually specifying the slug in the front matter of the post? For example: slug: Quiz to control the final permalink structure?

[dimaslanjaka]

@dimaslanjaka Can this issue be resolved by manually specifying the slug in the front matter of the post? For example: slug: Quiz to control the final permalink structure?

Aish.. I have 1200+ blog posts. Ahhh

[KUNDAN1334]

we don’t need to add slugs manually . a simple script can go through all the markdown files and auto-generate slugs based on file names or titles. Let me know if you’d like a sample script — it’ll save time.

[dimaslanjaka]

we don’t need to add slugs manually . a simple script can go through all the markdown files and auto-generate slugs based on file names or titles. Let me know if you’d like a sample script — it’ll save time.

which script ?

[KUNDAN1334]

We can use a simple Node.js script to add slugs automatically to the front matter of each markdown file. it will go through all your posts, check if a slug is already there, and if not then it will generate one from the file name and add it. so by using this way you don’t have to manually edit 1200+ files

[dimaslanjaka]

Thank you for your response.
However, asking users to manually update thousands of posts due to a breaking change in permalink behavior is not a practical solution.
This change introduces a major regression for long-time users who relied on the previous behavior where :title was based on the file path under source/_posts/.

A better approach would be to provide a configuration option or a compatibility mode to restore the old behavior, rather than forcing a massive manual migration that was never necessary before.

[dimaslanjaka]

I understand the new behavior, but manually editing thousands of existing posts isn’t feasible for long-term users.
This change breaks existing URLs and affects SEO and external links.
It would be much better to offer an option to keep the old permalink behavior (:title based on file path), instead of forcing users to adapt retroactively.

[dimaslanjaka]

With all due respect, this kind of breaking change without a fallback option creates unnecessary work and breaks URLs that have been stable for years.
It’s not just an inconvenience — it affects live blogs, SEO rankings, and user trust.
A configuration option to preserve the previous behavior would solve this without forcing mass edits.

[dimaslanjaka]

Serious impact on seo due to hexo

from page one to this rank

[dimaslanjaka]

@SukkaW @stevenjoezhang this is important

[yoshinorin]

@dimaslanjaka

Did you perhaps change new_post_name?

I couldn't determine whether changing the permalink has any side-effect of this issue. But, I’ve confirmed that the value of new_post_name affects the slug. I also confirmed that changing new_post_name to something like :year/:month/:day/:title.md even if :title is set in permalink triggers the issue you mentioned.

This issue is not limited to the latest version — it also occurs in v6.0.0. This part of the code has been present since the early implementation, though it's unclear whether this behavior was intentional.

If you can set new_post_name to :title, that might serve as a temporary workaround.

[dimaslanjaka]

@yoshinorin no no, new file name is only for hexo to create new post using command line. It will automatically create file under eg: 2025/05/sanitized-title.md.

I asked, why the permalink of :title changed ?. The previous :title permalink will follow the file path.

My case:

Permalink is :title.html.
Source post at source/_posts/GitHub/git-follow-symlink.md.
The permalink should be at https://www.webmanajemen.com/GitHub/git-follow-symlink.html (SHOULD BE LIKE THIS)
NOW, it changed without any backwards compatibility. Look https://www.webmanajemen.com/GitHub-git-follow-symlink.html (INVALID)

For now, i just backup old generated posts then restore to original permalink. BUT, it affects to SEO. Because doubled/duplicate posts which hexo made.

Look at this terrible generated files of hexo: https://github.com/dimaslanjaka/dimaslanjaka.github.io/tree/master

[yoshinorin]

@dimaslanjaka

I'd like to confirm a few points to align our understanding and clarify the issue:

Q1. Do you know which version you were using before the issue occurred?

You mentioned you’re using the latest Hexo, but if you know which version you were on before upgrading, please let us know.

Q2. About the generated files

Is my understanding correct that previously the generated URLs (files or directories) contained spaces (%20), but now they are replaced with hyphens (-), like this?

// source
source/_posts/GitHub/git follow symlink/index.md

// before update
- https://example.com/GitHub/git follow symlink/index.html
// after update
+ https://example.com/GitHub/git-follow-symlink/index.html

Or is it that the GitHub directory has disappeared and the article folder now appears right after the domain part, like this?

// before update
- https://example.com/git follow symlink/index.html
// after update
+ https://example.com/GitHub/git follow symlink/index.html

Thank you.