Skip to content

feat(validate_config): add warning about timezone #5731

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
stevenjoezhang wants to merge 1 commit into
base: master
Choose a base branch
from
+20 −1
Open

feat(validate_config): add warning about timezone #5731

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion lib/hexo/validate_config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import assert from 'assert';
import moment from 'moment-timezone';
import type Hexo from './index';

export = (ctx: Hexo): void => {
Expand All @@ -24,5 +25,23 @@ export = (ctx: Hexo): void => {
if (config.root.trim().length <= 0) {
throw new TypeError('Invalid config detected: "root" should not be empty!');
}
};

if (!config.timezone) {
log.warn('No timezone setting detected! Using LocalTimeZone as the default timezone.');
log.warn('This behavior will be changed to UTC in the next major version. Please set timezone explicitly (e.g. LocalTimeZone or America/New_York) in _config.yml to avoid this warning.');
} else {
const configTimezone = moment.tz.zone(config.timezone);
if (!configTimezone) {
log.warn(
`Invalid timezone setting detected! "${config.timezone}" is not a valid timezone.`
);
} else {
const machineTimezone = moment.tz.guess();
if (configTimezone.name !== machineTimezone) {
Comment on lines +39 to +40
Copy link
Copy Markdown
Member

@SukkaW SukkaW Jan 8, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have to guess and warn about a mismatch here? E.g., running Hexo on CI may have a different timezone, intentionally.

Copy link
Copy Markdown
Member

@yoshinorin yoshinorin Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes that the warning will always be displayed in CI environments. However, I think it should be displayed.

If the user's permalink setting includes time-based parts, it will also change the URLs of their posts.

As @stevenjoezhang mentioned in the above comment at #5720 (comment), my concern is that URLs may change.

Currently, URLs are always generated using the LocalTimeZone (machine's timezone) for date/time formatting. If we change it to use the Timezone from _config.yml for generating URLs in the next major version, and users are unaware that their machine's timezone and the timezone in _config.yml are inconsistent, the generated URLs could unintentionally change.

However, I do think it might be acceptable to address this by including a migration guide in the release notes instead of showing the warning.

Copy link
Copy Markdown
Member

@SukkaW SukkaW Feb 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about only giving this warning if this is not in CI? (In CI, there is nothing users can do anyway; they need to validate this on his/her local machine).

Also, since this only affects permalink patterns with time, we may emit this warning only when one of the permalink patterns uses time.

cc @stevenjoezhang

Copy link
Copy Markdown
Member Author

@stevenjoezhang stevenjoezhang Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@yoshinorin @SukkaW I believe that displaying a warning message is necessary both locally and in CI environments, because there is a possibility that links may change. Showing a clear warning is more reasonable than remaining completely silent. For example, if a user does not configure the time zone correctly and this causes the article links generated by CI to change, the issue can still be discovered by checking the CI logs.

I think we still have two tasks to complete:

  1. Check whether the permalink patterns contain time-related parameters, and use that as a condition for displaying the warning message.
  2. Write a migration notice in the release notes to inform users how to properly configure the time zone.

Copy link
Copy Markdown
Member

@yoshinorin yoshinorin Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@SukkaW @stevenjoezhang
I agree with only showing the warning when the permalink is affected.

As for CI environments, I don't think there's a reliable way to detect them. Even if there were, it would add unnecessary implementation complexity, so I think always showing the warning is fine. Instead of suppressing the warning in CI environments, it could help to make the warning message clearer, for example by including a link to the relevant documentation or this discussion.

log.warn(
`The timezone "${config.timezone}" setting is different from your machine timezone "${machineTimezone}". Make sure this is intended.`
);
}
}
}
};
Loading