DOCSEARCHbyAlgolia
Submit Docs

Hugo Themes Collection

repository·master·Indexed 23 days ago

https://github.com/gohugoio/hugothemes

A collection of community-created Hugo themes integrated into the official Hugo theme showcase at themes.gohugo.io. This repository provides instructions for installing themes, submitting new themes to the showcase, configuring theme.toml metadata, and using build scripts like generateThemeSite.sh and reviewTheme.sh for local testing and site generation.

Tokens
1.7K
Snippets
5
Records
10
Agent score
33%

What's inside hugothemes

  2. Handle Hugo Pipes assets for theme compatibility

    master

    If your theme uses Hugo Pipes methods like toCSS or PostCSS, you must commit the generated resources folder to your repository (or to exampleSite) so the theme works in environments without the full Hugo build pipeline.

    To generate these files:

    1. Run hugo server from the root of a Hugo project using your theme (generates /resources/).
    2. Or run hugo (generates public/resources).
    3. Copy the generated folder and commit it to your theme's root or exampleSite.

  3. Install all Hugo themes

    master

    To install the entire collection of available Hugo themes, clone the repository recursively into a themes directory within your working directory.

    git clone --depth 1 --recursive https://github.com/gohugoio/hugoThemes.git themes

  4. Perform a quick build for theme reviews or tests

    master

    To test a single theme without building the entire site, use the ./reviewTheme.sh script. This script uses a dedicated directory (defaulting to ./review) to store themes, which significantly reduces build time.

    To run a review, provide the URL to the Git repository containing the theme you wish to test. You can optionally specify a custom directory for the theme storage using the -t flag.

    Note: If the theme is not already whitelisted in ./generateThemeSite.sh, you may need to add it there first.

    Once the script runs, the Hugo theme site is automatically served at http://localhost:1313.

    ./reviewTheme.sh <repo> -t <path>

  5. Add a theme to the Hugo Themes Showcase

    master

    To have your theme automatically added to themes.gohugo.io, follow these steps:

    1. Create the theme: Use hugo new theme <THEMENAME>.
    2. Test compatibility: Ensure it works against the Hugo Basic Example.
    3. Add metadata: Create a theme.toml file in the theme root.
    4. Add documentation: Include a descriptive README.md in the theme root.
    5. Add media: Place a thumbnail at [ThemeDir]/images/tn.png and a screenshot at [ThemeDir]/images/screenshot.png.
    6. Submit: Open a GitHub issue with a link to your theme's repository. Do not open a pull request.

    Requirements for inclusion:

    • Must have an Open Source license.
    • Must include the resources folder if using Hugo Pipes.
    • exampleSite/config.{toml, yaml, json} must use https://example.com as the baseurl.
    • The exampleSite should not have third-party tracking (analytics, etc.) enabled with real IDs.

  6. Perform a complete build of the Hugo theme site

    master

    Use the ./generateThemeSite.sh script to generate the full Hugo theme site (the site seen at themes.gohugo.io). This process downloads all themes listed in the repository.

    Warning: This is a resource-intensive operation that requires significant disk space and a long execution time.

    To test the complete build locally, pass the root of your local baseUrl as the first argument.

    ./generateThemeSite.sh http://localhost:1313

  7. Test your theme locally with the build script

    master

    You can test how your theme will appear on the Hugo Themes website by using the local review script:

    1. Clone the hugoThemes repository.
    2. Navigate to the _script/ directory: cd _script/.
    3. Run the review script with your theme's Git URL: ./reviewTheme.sh <URL_TO_THEME_GIT_REPO>.
    4. Open http://localhost:1313 in your browser.

    If your theme requires a non-standard content structure, you may need to whitelist it in ./generateThemeSite.sh.

  8. Configure build repositories via environment variables

    master

    You can customize which repositories are used during the build process by setting the following environment variables before running ./generateThemeSite.sh:

    • HUGO_THEMES_REPO: Specifies the repository containing all themes to be displayed.
    • HUGO_THEME_SITE_REPO: Specifies the repository used for the Hugo theme site itself.
    • HUGO_EXAMPLE_SITE_REPO: Specifies the repository used for the Hugo example site.
    HUGO_THEMES_REPO=<repo> ./generateThemeSite.sh http://localhost:1313

HUGO_THEME_SITE_REPO=<repo> ./generateThemeSite.sh http://localhost:1313

HUGO_EXAMPLE_SITE_REPO=<repo> ./generateThemeSite.sh http://localhost:1313

  9. Configure theme.toml metadata

    master

    The theme.toml file is the only accepted metadata format (do not use .yaml or .json). It must be located at the root of your theme.

    Required fields include name, license, licenselink, description, homepage, tags, features, and min_version. Note that min_version must use full semver (e.g., 0.59.0 instead of 0.59).

    name = "Theme Name"
license = "MIT"
licenselink = "Link to theme's license"
description = "Theme description"
homepage = "Website of your theme"
tags = ["blog", "company"]
features = ["some", "awesome", "features"]
min_version = "0.59.1"

# 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"

  10. Avoid common permalink and asset issues in themes

    master

    To ensure your theme works correctly when hosted in a subdirectory (like the Hugo Themes showcase):

    • Use absolute URLs for inline styles: e.g., <div style="background: url('{{ "images/background.jpg" | absURL }}')">.
    • Avoid leading slashes in URLs: Do not start URLs with / as they will point to the host root instead of the theme's subdirectory.
    • Use HTTPS for CDNs: If loading external CSS/JS from a CDN, use https. Do not use relative protocol URLs (e.g., //cdn.com/...).