Recently I have realized, that I need to test my Hugo theme locally for prevent the issues with assets before commit the changes to the theme repository.
I have the separate projects: one for working on theme template and compiling the assets (js,css) and the second project is the theme with optimized assets, that I shared with community.
As many Hugo themes my theme has the exampleSite folder with the test content and configuration.
So how to test the theme on the local machine without creating an additional Hugo project?
I have found this solution, that worked for me. As example for the Yourfolio theme:
$ git clone https://github.com/serg/yourfolio.git
$ cd yourfolio
$ hugo server -s exampleSite --themesDir=../..
The website will be available in browser at this path localhost:1313
Please note: this solution will be working for themes with the exampleSite folder. Not tested for themes with different content organization and configuration.
Hope it will be useful for the theme developers and people who need to try a theme locally before adding it to theirs Hugo project.
Also I would like to mention how to test a theme when you added it to the themes folder of your existing Hugo project. Inside your Hugo project folder run for e.g. this command:
$ hugo server -s themes/yourfolio/exampleSite --themesDir=../..
In this case you can test certain theme inside your themes folder without affecting the files that placed in your existing Hugo project.
Please feel free to share your solutions according to this topic or if you have some ideas/improvements.
With theme components, that convention is changing for me at least (because on Netlify, the cloned repo dir name is always “repo”). So the theme name “seen” by hugo at “…/…” is “repo” even if the theme is named “foo”.
Workaround (for a theme named “foo”):
mkdir -p exampleSite/themes/
cd exampleSite/themes/
ln -s ../.. foo
Ensure that the exampleSite’s config.toml has theme = "foo".
I happened to make a commit related to this earlier today. That was needed because with theme components, now the theme names are hard-coded in theme’s config.toml:
I don’t understand what you are saying, but if you for some reason (I don’t see why) need to resolve to symbolic link magic to use the “…/…” trick, then we should fix that in Hugo. Can you create an issue?
I am not clear what the issue definition should be… the problem is that now themes need to hardcode the theme name in their config.toml in the theme parameter. This would always be the case if they are using theme components.
The “fix” would possibly be to have a separate parameter as I had suggested here? That way no matter what name a theme gets cloned as, it doesn’t matter.
Currently Netlify clones any repo (theme repo in the case of exampleSite) as “repo”…
A theme “foo” would have theme = ["foo-comp-1", "foo"], but because of themeDir = "../..", Hugo would only “see” the “repo” dir that Netlify cloned… so the Netlify build will fail saying something like:
Error: Unable to find theme Directory: /opt/build/repo/exampleSite/…/…/foo
So in my above workaround, I need to make the symlink name match the theme name:
ln -s ../.. foo
Best solution would have been to add themeComponents or something like that, a list parameter just to hold the component names, and leave the original theme parameter as a single string value.
As theme components are not yet in wide spread use, would be great if you too think that that’s a reasonable solution and make that quick breaking change .
You and I have a different definition of “hardcoded”. A value compiled from a Go file is hardcoded. A value in a config.toml is not. We’re not adding “another” list, and I still don’t understand the problem. I will have a look at it later.
But I will add that this thread started with an exellent tip about how to test your themes locally. So this discussion sounds more and more off-topic.
I agree. It was sort of on-topic because the themeDir = "../.." stopped working for themes with components. I will open a different thread when I get a chance.
.