HUGO

  • News
  • Docs
  • Themes
  • Community
  • GitHub
Star

What's on this Page

    • tl;dr
    • Theme Requirements
      • Add Your Theme to the Repo
      • Create a theme.toml File
      • Images
      • Create a README File
        • Example README.md
CONTRIBUTE

Add Your Hugo Theme to the Showcase

If you’ve built a Hugo theme and want to contribute back to the Hugo Community, add your theme to the Hugo Showcase.

A collection of all themes created by the Hugo community, including screenshots and demos, can be found at https://themes.gohugo.io. Every theme in this list will automatically be added to the theme site. Theme updates aren’t scheduled but usually happen at least once a week.

tl;dr

  1. Create your theme using hugo new theme <THEMENAME>;
  2. Test your theme against https://github.com/spf13/HugoBasicExample *
  3. Add a theme.toml file to the root of the theme with all required metadata
  4. Add a descriptive README.md to the root of the theme source
  5. Add /images/screenshot.png and /images/tn.png

* If your theme doesn’t fit into the Hugo Basic Example site, we encourage theme authors to supply a self-contained Hugo site in /exampleSite.

The folder name here—exampleSite—is important, as this folder will be picked up and used by the script that generates the Hugo Theme Site. It mirrors the root directory of a Hugo website and allows you to add custom content, assets, and a config file with preset values.

See the Hugo Artist theme’s exampleSite for a good example.

Please make your example site’s content is as neutral as possible. We hope this goes without saying.

Theme Requirements

In order to add your theme to the Hugo Themes Showcase, the following requirements need to be met:

  1. theme.toml with all required fields
  2. Images for thumbnail and screenshot
  3. A good README file instructions for users
  4. Addition to the hugoThemes GitHub repository

Add Your Theme to the Repo

The easiest way to add your theme is to open up a new issue in the theme repository with a link to the theme’s repository on GitHub.

Create a theme.toml File

theme.toml contains metadata about the theme and its creator and should be created automatically when running the hugo new theme. The auto-generated file is provided here as well for easy downloading:

theme.toml

name = ""
license = "MIT"
licenselink = "https://github.com/<YOURNAME>/<YOURTHEME>/blob/master/LICENSE.md"
description = ""
homepage = "https://example.com/"
tags = []
features = []
min_version = 0.19

[author]
  name = ""
  homepage = ""

# If porting an existing theme
[original]
  name = ""
  homepage = ""
  repo = ""

The following fields are required:

name = "Hyde"
license = "MIT"
licenselink = "https://github.com/spf13/hyde/blob/master/LICENSE.md"
description = "An elegant open source and mobile first theme"
homepage = "http://siteforthistheme.com/"
tags = ["blog", "company"]
features = ["blog"]
min_version = 0.13

[author]
    name = "spf13"
    homepage = "http://spf13.com/"

# If porting an existing theme
[original]
    author = "mdo"
    homepage = "http://hyde.getpoole.com/"
    repo = "https://www.github.com/mdo/hyde"
  1. This is different from the theme.toml file created by hugo new theme in Hugo versions before v0.14.
  2. Only theme.toml is accepted; ie. not theme.yaml andnot theme.json.

Images

Screenshots are used for previews in the Hugo Theme Gallery. Make sure that they have the right dimensions:

  • Thumbnail should be 900px × 600px
  • Screenshot should be 1500px × 1000px
  • Media must be located in
    • /images/screenshot.png
    • /images/tn.png

Additional media may be provided in the same directory.

Create a README File

Your theme’s README file should be written in markdown and saved at the root of your theme’s directory structure. Your README.md serves as

  1. Content for your theme’s details page at https://themes.gohugo.io
  2. General information about the theme in your GitHub repository (i.e., it’s usual purpose)

Example README.md

You can download the following README.md as an outline:

README.md


# Theme Title

**Need input from @digitalcraftsman on what could be added to this file.**




If you add screenshots to the README, please make use of absolute file paths instead of relative ones like /images/screenshot.png. Relative paths work great on GitHub but they don’t correspond to the directory structure of themes.gohugo.io. Therefore, browsers will not be able to display screenshots on the theme site under the given (relative) path.

See Also

  • Roadmap
  • Create a Theme
  • Install and Use Themes
  • Customize a Theme
  • Contribute to the Hugo Docs
  • About Hugo
    • Overview
    • Hugo Features
    • The Benefits of Static
    • Roadmap
    • License
  • Getting Started
    • Get Started Overview
    • Quick Start
    • Install Hugo
    • Basic Usage
    • Directory Structure
    • Configuration
  • Themes
    • Themes Overview
    • Install and Use Themes
    • Customize a Theme
    • Create a Theme
  • Content Management
    • Content Management Overview
    • Organization
    • Supported Content Formats
    • Front Matter
    • Shortcodes
    • Related Content
    • Sections
    • Types
    • Archetypes
    • Taxonomies
    • Summaries
    • Links and Cross References
    • URL Management
    • Menus
    • Table of Contents
    • Comments
    • Multilingual and i18n
    • Syntax Highlighting
  • Templates
    • Templates Overview
    • Introduction
    • Template Lookup Order
    • Custom Output Formats
    • Base Templates and Blocks
    • List Page Templates
    • Homepage Template
    • Section Templates
    • Taxonomy Templates
    • Single Page Templates
    • Content View Templates
    • Data Templates
    • Partial Templates
    • Shortcode Templates
    • Local File Templates
    • 404 Page
    • Menu Templates
    • Pagination
    • RSS Templates
    • Sitemap Template
    • Robots.txt
    • Internal Templates
    • Alternative Templating
    • Template Debugging
  • Functions
    • Functions Quick Reference
    • .AddDate
    • .Format
    • .Get
    • .GetPage
    • .Param
    • .Scratch
    • .Unix
    • Math
    • absLangURL
    • absURL
    • after
    • apply
    • base64
    • chomp
    • countrunes
    • countwords
    • dateFormat
    • default
    • delimit
    • dict
    • echoParam
    • emojify
    • eq
    • findRE
    • first
    • ge
    • getenv
    • gt
    • hasPrefix
    • highlight
    • htmlEscape
    • htmlUnescape
    • humanize
    • i18n
    • imageConfig
    • in
    • index
    • int
    • intersect
    • isset
    • jsonify
    • lang.NumFmt
    • last
    • le
    • lower
    • lt
    • markdownify
    • md5
    • ne
    • now
    • partialCached
    • plainify
    • pluralize
    • print
    • printf
    • println
    • querify
    • range
    • readDir
    • readFile
    • ref
    • relLangURL
    • relURL
    • relref
    • render
    • replace
    • replaceRE
    • safeCSS
    • safeHTML
    • safeHTMLAttr
    • safeJS
    • safeURL
    • seq
    • sha
    • shuffle
    • singularize
    • slice
    • slicestr
    • sort
    • split
    • string
    • strings.TrimLeft
    • strings.TrimPrefix
    • strings.TrimRight
    • strings.TrimSuffix
    • substr
    • time
    • title
    • trim
    • truncate
    • union
    • uniq
    • upper
    • urlize
    • urls.Parse
    • where
    • with
  • Variables
    • Variables Overview
    • Site Variables
    • Page Variables
    • Shortcode Variables
    • Taxonomy Variables
    • File Variables
    • Menu Variables
    • Hugo Variables
    • Git Variables
    • Sitemap Variables
  • CLI
  • Troubleshooting
    • Troubleshoot
    • Accented Characters in URLs
    • Build Performance
    • EOF Error
  • Tools
    • Developer Tools Overview
    • Migrations
    • Starter Kits
    • Frontends
    • Editor Plug-ins
    • Search
    • Other Projects
  • Hosting & Deployment
    • Hosting & Deployment Overview
    • Host-Agnostic Deploys with Nanobox
    • Host on Netlify
    • Host on Firebase
    • Host on GitHub
    • Host on GitLab
    • Host on Bitbucket
    • Deployment with Wercker
    • Deployment with Rsync
  • Contribute
    • Contribute to Hugo
    • Development
    • Documentation
    • Themes
“Add Your Hugo Theme to the Showcase” was last updated: October 13, 2017: Initial commit (a48229f)
Improve this page
By the Hugo Authors

The Hugo logos are copyright © Steve Francia 2013–2017.

The Hugo Gopher is based on an original work by Renée French.

  • File an Issue
  • Get Help
  • Discuss the Source Code
  • @GoHugoIO
  • @spf13
  • @bepsays
  • News
  • Docs
  • Themes
  • Community
  • GitHub
  • About Hugo
  • Getting Started
  • Themes
  • Content Management
  • Templates
  • Functions
  • Variables
  • CLI
  • Troubleshooting
  • Tools
  • Hosting & Deployment
  • Contribute