Hugo themes

This repository contains a list of themes developed by the Hugo community, which can be accessed at themes.gohugo.io. For any queries, refer to the FAQ section provided below.

Adding a theme

You can use the command hugo new theme THEME_NAME to create a new theme.

Then, from the root of your theme's repository, you need to perform the following steps:

Create a config.toml file that specifies the Hugo version(s) supported by your theme. Also, add a theme.toml file and include some relevant metadata about the theme (see below).
Add a descriptive README.md (see below).
Include a screenshot image in /images/screenshot.{png,jpg} and a thumbnail image in /images/tn.{png,jpg} (see below).
Push the changes.

After making your theme available online, you can include it here by following the steps mentioned below.

Clone this repository

git clone https://github.com/gohugoio/hugoThemesSiteBuilder.git

Add your theme's URL (e.g. github.com/user/my-blog-theme) in themes.txt in lexicographical order.
Write a meaningful commit message (e.g. Add theme my-blog-theme).
Create a pull request(PR) and ensure that the preview looks good.

If the PR preview does not appear as expected after you have fixed your theme (missing thumbnail image for example), you can trigger a new preview build as follows.

Amend the commit in your PR branch
```
git commit --amend --no-edit
```
Do a force push
```
git push -f
```

Note: The themes site is rebuilt on a daily basis using the list of themes present in this repository. Any changes made to an existing theme will be reflected on the website within 24 hours.

Theme configuration

Your theme should have a theme.toml file in the root directory. This file should contain relevant metadata about the theme and its creator(s). It's important to note that only the theme.toml file format is supported. theme.yaml or theme.json files are not supported currently.

name = "Theme Name"
license = "MIT"
licenselink = "Link to theme's license"
description = "Theme description"

# The home page of the theme, where the source can be found.
homepage = "https://github.com/gohugoio/gohugoioTheme"

# If you have a running demo of the theme.
demosite = "https://gohugo.io"

tags = ["blog", "company"]
features = ["some", "awesome", "features"]

# If the theme has multiple authors
authors = [
  {name = "Name of author", homepage = "Website of author"},
  {name = "Name of author", homepage = "Website of author"}
]

# If the theme has a single author
[author]
    name = "Your name"
    homepage = "Your website"

# If porting an existing theme
[original]
    author = "Name of original author"
    homepage = "His/Her website"
    repo = "Link to source code of original theme"

Your theme should also have a configuration file (such as config.toml) that specifies the Hugo versions supported by the theme.

[module]
  [module.hugoVersion]
    extended = true
    min = "0.55.0"
    max = "0.84.2"

You may omit the fields extended, min, or max.

Theme maintainers are requested not to delete Git references or tags from your theme's repository. Doing so may cause issues with fetching specific version of a module, leading to errors.

Media

Screenshots are used as theme previews in the list. They should feature a theme's layout (without any browser chrome or device mockups) and have the following dimensions:

Both the Thumbnail and Screenshot must be in 3:2 aspect ratio.
Screenshot (screenshot.png or screenshot.jpg) should have a dimension of at least 1500×1000 in pixels.
Thumbnail (tn.png or tn.jpg) should have a dimension of at least 900×600 in pixels.
Media must be located in:
- [ThemeDir]/images/screenshot.{png,jpg}
- [ThemeDir]/images/tn.{png,jpg}

Additional media may be provided in the same directory.

README.md

Your theme's README file (which should be written in Markdown and called README.md) serves a two purposes. It's content appears in two places, which are:

On your theme's detail page on themes.gohugo.io website.
On your theme's regular main page at GitHub/GitLab (as usual).

To make your theme more accessible to users across the globe, it would be helpful if you could include an English translation of the README, at the very least.

Note: If you add screenshots to the README, please make sure to use absolute file paths instead of relative ones (like /images/screenshot.png). Relative paths work great on GitHub/GitLab, but they don't correspond to the directory structure of themes.gohugo.io website. Therefore, browsers will not be able to display screenshots if relative paths are used.

Criteria for acceptance of a theme

Forks must be notably different

A theme based on an existing Hugo theme (aka a fork) must be notably different for it to be considered a separate theme altogether. In such cases, you should list few arguments in README.md file mentioning why your theme should be included.

The definition of notably different can be subjective, but in most cases, it should be clear. Simply changing the background color or changing few styles, for instance, does not make a theme notably different. It would be better if you submit a pull request to the original theme to include your proposed changes.

LICENSE

Themes in this repository are accepted only if they come with an Open Source license that allows for the theme to be freely used, modified, and shared. To view a list of popular licenses, you can visit Open Source Initiative website.

License of derivative works

If you are porting an existing theme from another platform to Hugo, or if you're forking an existing Hugo theme to incorporate new features and plan to submit the derivative work; it's essential to ensure that the original theme's license requirements are met.

In case the original theme lacks an Open Source license, you should try to obtain one from the creator of the original work. You cannot add a license on your own. Such derivative work where license of the original work is unclear, will not be accepted.

In any other case, if a submission is found to be in violation of licence of the original work, it will be rejected without further discussion.

Other criteria

Themes with READMEs set up as marketing campaigns for other products (e.g. paid version of a free theme) will not be accepted.

Note on outdated themes

Themes that have not been updated in the past few years are removed as per the current policy. Even if your theme is fully functional, it is recommended that you periodically check and confirm its compatibility with the latest versions of Hugo.

FAQ

Question: My theme is flagged as 'old' when it's been updated recently.

Answer: We use Hugo Modules to manage the themes -- which is backed by Go Modules. If you have one or more tagged releases (e.g. v1.0.0), we will choose the last version within the current major version. To get rid of that warning you need to tag a new release and wait for us to rebuild the theme site. Note that for unversioned themes, the latest commit gets picked.

Question: Can I submit a theme with a repository hosted on git.sr.ht (or any other platform for that matter), given that themes.txt contains links to github.com and gitlab.com?

Answer: Yes, it would be accepted if the repository hosted on git.sr.ht (or any other platform) is supported by Go Modules. To confirm the same, you can create a pull request and check if the build process succeeds.

peaceiris / hugoThemesSiteBuilder