hexo
hexo copied to clipboard
The proposal of installing theme through npm
The original discussion is at #2471
Here is my proposal:
- We should not treat
hexo-theme-
prefixed package as a hexo plugin. See @tomap 's commit: https://github.com/hexojs/hexo/compare/master...tomap:feature/themeAsPackagediff-3d0f701643104f3b0e388b8f6a9a7f3eR38 - Users are still required to specify their theme's name in
_config.yml
, because... - Hexo will read
themes/[name]
directory first, then searchhexo-theme-[name]
directory undernode_modules
. It means the theme underthemes
directory should have higher priority. In this way no extratheme_from_npm: true
configuration is needed. -
theme_config
in_config.yml
looks good, but it is better to have a separate theme config. We could introduce_config.[name].yml
. Currently,theme_config
has higher priority than_config.yml
under theme directories. After bring up_config.[name].yml
, I suggest thetheme_config in _config.yml > _config.[name].yml > _config.yml under theme directories
which will retain highest priority fortheme_config
. - ~~Also, we need to fix the issue that some plugins can not read theme config from
theme_config
: https://github.com/hexojs/hexo/issues/2471#issuecomment-557877081~~
IMHO, we could easily bring up this feature without any Breaking Changes: the theme structure, current configurations and setup will not be affected. Yes, I mean we can even bring up this feature during Hexo 4.x development.
cc @hexojs/core @jiangtj
FYI:
Currently there are more than 50 packages on npm has hexo-theme-
prefixed: https://www.npmjs.com/search?q=hexo-theme (Others are eslint-config-theme-next
or -theme-hexo
suffixed)
We should not treat hexo-theme- prefixed package as a hexo plugin.
Is there a good way to handle this situation? Plugin: https://www.npmjs.com/package/hexo-theme-next-anchor Theme: https://www.npmjs.com/package/hexo-theme-next
We should not treat hexo-theme- prefixed package as a hexo plugin.
Is there a good way to handle this situation? Plugin: https://www.npmjs.com/package/hexo-theme-next-anchor Theme: https://www.npmjs.com/package/hexo-theme-next
We could contact all owners of hexo-theme-*
on npm.org when they are not themes
The package hexo-theme-next-anchor is indeed a plugin. We should suggest the owner to change it's name (21 downloads per week)
For the package hexo-theme-next, it is a theme. so, in this case, no problem
@SukkaW I edited your issue to add numbers for each items
for 1. indeed, that is the pre requisite but in the list of packages on npm, as you mentioned, there are multiple packages prefixed "hexo-theme-*" I looked at each of them, and I believe that none are plugins, except one: https://www.npmjs.com/package/hexo-theme-next-anchor => not a big deal. we'll contact the owner And we have to decide is that means waiting for Hexo 5 or a smaller 4.1 could be ok
for 2. ok
for 3. ok, but it will make the code a bit more complex because the theme_dir will be more complex to determine (not a big deal either)
for 4. ok also, but this is a bonus
for 5. this is not really a bonus, because without that, we cannot customize .less (and I believe it is probably the same for .sass
If I have time, I'll start with 3. (I don't have a lot of time those days, but maybe...)
hexo-theme-*
is treated as a theme by default, so this is not a problem, just contact the owner to modify it.
@stevenjoezhang rename hexo-theme-next-anchor
to hexo-next-anchor
, maybe better. Or load
all hexo-theme-next-*
plugin manual.
https://github.com/hexojs/hexo/blob/master/lib/hexo/load_plugins.js#L51
IMHO, distinguishing between a theme and a plugin is not complicated, you just need to determine whether a layout
directory exists - it is a pity to deprecate some modules for this reason.
cc @1v9
Great proposal! Would love to use this feature.
you just need to determine whether a
layout
directory exists - it is a pity to deprecate some modules for this reason.
Another idea is only to exclude hexo-theme-[config.theme]
from being loaded as a plugin. But it means installing multiple themes will become impossible.
cc @stevenjoezhang @tomap @jiangtj
Also, we need to fix the issue that some plugins can not read theme config from theme_config: #2471 (comment)
I just retested the item 5. and it seems to work without my changes. I must have tested wrong :)
Another idea is only to exclude
hexo-theme-[config.theme]
from being loaded as a plugin. But it means installing multiple themes will become impossible.
This brings me to another idea. We can configure in the configuration file, which need to be excluded
@tomap Yeah, theme_config
is supposed to be included in Locals.prototype.theme
.
https://github.com/hexojs/hexo/blob/5fba0a08bf1e7eaa81bf9156f6bd1e83b1e500a0/lib/hexo/index.js#L360
@jiangtj It would be more complex for a user to configure it.
This brings me to another idea. We can configure in the configuration file, which need to be excluded
https://github.com/hexojs/hexo/issues/2471#issuecomment-557870309
Related progress.
@tomap We could start by excluding hexo-theme-${config.theme}
from being loading as a plugin.
Since this is already in progress, I'm unpinning this in favor of https://github.com/hexojs/hexo/issues/4260.
https://github.com/hexojs/hexo/pull/4120#issuecomment-619574347
@SukkaW Maybe it's possible to release npm themes support before of Hexo 5? I'd like to have it without waiting for next release of Hexo.
@stevenjoezhang
https://github.com/hexojs/hexo/pull/4120#issuecomment-619574347
Is it possible to merge config.theme_config into theme.config after ctx.theme loads?
The ctx.theme.config
is loaded through this.theme.process()
:
https://github.com/hexojs/hexo/blob/edef5c2a9c1217aaab02f64397e7e94d2f98e4fa/lib/hexo/index.js#L306-L309
See: https://github.com/hexojs/hexo/blob/master/lib/theme/index.js ,
https://github.com/hexojs/hexo/blob/edef5c2a9c1217aaab02f64397e7e94d2f98e4fa/lib/theme/processors/config.js#L11-L14
That's right before this._generate()
(Before posts are rendered, before this.generateLocals()
began to build locals).
When executing hexo clean
, customThemeName
here is always the default value landscape
https://github.com/hexojs/hexo/blob/14890743dd00e1a1e7c4bd9c7ef632f609d35a4c/lib/hexo/load_plugins.js#L44-L45
This will cause Hexo to load all themes except landscape as plugins.
See also https://github.com/next-theme/hexo-theme-next/issues/65
CC @hexojs/core
@stevenjoezhang
This will cause Hexo to load all themes except landscape as plugins.
Might be related with https://github.com/hexojs/hexo/pull/4386.
How about load the plugins in theme's dependencies?
See my theme. I have add those needed dependencies. https://github.com/jiangtj/hexo-theme-cake/blob/91036aa12be4a577705b990252367a93ea089b18/package.json#L47-L50
These plugins are required, but user muse install them in their blog project
Here is a my solution, but I think it’s best done in hexo, do you think? https://github.com/jiangtj/hexo-theme-cake/blob/91036aa12be4a577705b990252367a93ea089b18/lib/load.js#L24-L27 https://github.com/jiangtj/hexo-theme-cake/blob/91036aa12be4a577705b990252367a93ea089b18/lib/utils.js#L34-L40
@jiangtj
By default npm i hexo-theme-[theme's name]
should install those dependencies
and theme could access them.
So what you need is to make the theme loading required hexo's plugin, right?
My thought is to include those plugins inside dependencies
so the npm i
will be able to install them as well. We could also introduces a new entry to package.json
, which will tell hexo plugins to be loaded.
So what you need is to make the theme loading required hexo's plugin, right?
My thought is to include those plugins inside
dependencies
so thenpm i
will be able to install them as well. We could also introduces a new entry topackage.json
, which will tell hexo plugins to be loaded.
Yesh
What about these kind of issues :
- Changing some color variables from a CSS file : https://github.com/hexojs/hexo-theme-landscape/issues/186
- Changing or adding a new lang in
languages/mylang.yml
Because with a npm module you don't want to change any of node_modules/theme/
files. So have you an idea for file override other than for _config.yml
with Alternate Theme Config.
What about these kind of issues :
- Changing some color variables from a CSS file : Colors from _config.yml hexo-theme-landscape#186
- Changing or adding a new lang in
languages/mylang.yml
Because with a npm module you don't want to change any of
node_modules/theme/
files. So have you an idea for file override other than for_config.yml
with Alternate Theme Config.
Hindsight is 2020. We could have refused to automatically merge arrays, too late.
Ideas:
- $diff/Opt-out/filter config that allows filtering elements out of arrays
- Use intermediary config that allows hard resetting.
- We could allow changing the merge strategy to "simple".
- we could add a schema and theme version to the config, which would determine how we migrate it to the latest version in steps.
- we could allow object values on strings to define special behavior like
{ $enabled: false, $value: "cloud" }
Tu change color, you can rely on variables that go from config to css. I did that in my theme with stylus
https://github.com/tomap/hexo-theme-minidyne/blob/9bcd4e4e9b07d14db456978c7d5d12876380a132/source/css/style.styl#L3
Declare a variable with proper name and boom
@tomap ... check the title... what we're trying to do with Hexo 5 is configure the theme, not modify it's internals with no restrictions and breaking all hope of upgradeability. We only have the ability to modify the theme using predefined endpoints, like _confgi.landscape.yml.
Case study of a mid sized mod to the landscape theme: vblip.com
- I needed to modify 2 top level objects in _config.yml
- overriding rss is confusing... I can do it, but it contradicts the idea that the theme config takes presence.
- I had to modify quite a few styles. There is an _extend file in the theme, but that's internal and full of values. I ended up practically forking 4 style sheets for the nav bar and some articles. I wouldn't have had to do that if an _extend.scss file was exposed to me. A few user customizable style options like hide_date on pages would have been nice, but probably unnecessary.
- lastly, there is very little JavaScript, which is good, but it runs in a very old school manner. Given all evergreen browsers support modules, having the nav bar code be in one exported function and giving users a 3 line JavaScript file we could override would be nice.
Sorry for the late reply. Modifying the layout and styles with Hexo can be difficult because different themes use different template engines and have different code styles. Hexo provides an injector that allows you to insert HTML code at specific locations, but for more precise customization, the theme needs to provide relevant interfaces. Here are my suggestions:
-
You can try using the plugin https://github.com/jiangtj/hexo-extend-theme, which allows you to replace any file in the theme.
-
You can fork the theme and use it. In fact, themes like "landscape" are not updated frequently, so you can easily follow the upstream updates.
I will close this issue because the main problem has been resolved. If you have any new questions, please feel free to open a new issue.