Is there any stuff out there which is used to help port Jekyll themes to Hugo? Let’s say, I wanna port this Jekyll theme [1].
Hello @milabsgo,
we would appreciate any kind of new themes. After porting several themes to Hugo I could summarize my workflow. It should probably be written down as a more detailed guide including some best practices.
There is a tutorial about Creating a new theme that could help. Some aspects of the port might require a bit more research (depending on level of experience). This way I learnt the concepts of Hugo.
However, let’s summarize my workflow:
Create a development environment
This means I create a new Hugo site usually called <THEME-NAME>-env where I can play with different kind of content structures, configurations etc. without interfering other themes. Within this Hugo site I create a new theme which is simultaneously my Git repository that I use for version control.
# create a new hugo site
hugo new site my-theme-env
# enter this directory
cd my-theme-env
# create a new theme
hugo new theme my-theme
cd cd my-theme
# initialize a git repository
git init
Copy all assets
Next, I copy all assets (images, CSS and JS files etc.) into the static folder of the theme (my-theme/static) and (mostly) keep the original folder structure.
Don’t forget to commit from time to time.
Header and footer partials
Now you can also start the built-in server of Hugo to view changes live in the browser while adding more code in the future .
# inside my-theme-env run
hugo server
Open the browser and enter localhost:1313 (default url) to see your site. By now it’s just a blank site.
Since most sites depend on assets like stylesheets (CSS) and Javascript I create two partials: one for the header and another one for the footer.
I investigate the template structure of the theme I want to port and extract the necessay parts (HTML) of the header and footer and translate them into a template language that Hugo can understand (mostly Go’s templating language).
Don’t forget to change urls to linked ressources, especially the copied CSS and JS files.
The homepage
In this step I begin to work with the homepage represented by the index.html template at my-theme/layouts/index.html.
The header and footer are parts of each page so we should include them into the homepage (index.html):
{{ partial "header.html" . }}
{{ partial "footer.html" . }}
Don’t forget the dot at the end!
Now, Hugo should reloaded our page in the browser due to the changes in the templates we made a few moments ago. Press F12 to open the developer tools of your browser and look for a tab called console. If you don’t see any errors everything is ok.
Otherwise check the links to the files (CSS, JS) in the header and footer partial.
Build up a foundation
In this step we can begin with the actual work of porting the theme. I break down the original theme into smaller chunks that can be put into a partial (things like navigations, menus or sidebar). We will reuse them later on other kind of pages. Alternatively, you can follow the template structure of the orignal theme and translate it partial by partial.
By importing the partials afterwords I see the theme growing step by step. I do this step iteratively until the homepage looks like the original one.
We build up a good foundation of other kind of pages like single articles etc. that differ slightly in their structure.
Single and list pages
Single pages represent content files whose look is defined by the template my-theme/layouts/_default/single.html.
Include again all common elements (header, footer, navigation…) as partials into the page as well and add the missing HTML that makes a single page.
There are also list pages that are used to list all the contents of a section (e.g. blog) or categories and tags. You can find the corresponding template under my-theme/layouts/_default/list.html. Its translation follows the same iterative approach that we used so far.
This guide shows roughly my workflow of porting a theme to Hugo. It’s also a good idea to look at existing themes to see how they solved a particular problem that you might face.
Share your theme
Once you ported the theme it would be great if you could share it with the community. We curate a list of existing open source themes that is used to build the theme gallery.
To add your theme to the list follow this last steps to add a few metadata to your theme.
1 Like
@digitalcraftsman
Thank you for sharing your experience of how to port other themes to hugo. That’s very helpful and useful.
And then, I will attemp to follow the workflow you descripted around here in order to port a Jekyll theme to Jugo. After done successfully, I will share my experience and the ported theme with open source with the community. At that point, I hope that there is a little bit help for other guys who would like to port one of Jekyll thems to Hugo.
This forum already contains a lot of helpful comments from users who faced the same problems. Otherwise feel free to ask.
Have you ever had to work with .sass files?
I want to port a jekyll theme that uses node to compile .sass. I am thinking it would be easiest to compile them all and manually port over the static .css files that are generated.
Is there any reason you would dissuade me from doing so?
Sass is really flexible once you get to know it and, you can put it together in a pipeline to automatically do other needed steps like minification.