mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
ba45da9d03
32356e4e Fix typo in header of shortcode-templates.md c8f1a2d2 Correct code example for index template function bfa6a55d Escape code fencing ff8b2f99 Fix typos in deployment with wercker tutorial 557c36e8 theme: Merge commit '7fbb4bed25001182bfeb91f79db0f0c1936582ee' 7fbb4bed Squashed 'themes/gohugoioTheme/' changes from 7dd8a302..ca53082d ce31cee0 Add "See Also" config 158cee1b Make the tags into keywords 61600be6 Add a note to the related section 49edb5a2 Relase 0.27.1 c9bbc001 releaser: Add release notes to /docs for release of 0.27.1 213c6c3b Add bugs poster 8b4590cd Add KeyCDN integration tutorial 2b277859 Add tutorial videos to several docs pages 950fef1f Update roadmap to link to the correct milestones page 496f5bf6 Rename relnotes d6f9378d Bump Netlify versions to 0.27 087fde7f Update 0.27 release notes 603f94ae docs: Document Related Content 3790f6a3 releaser: Bump versions for release of 0.27 0948868c releaser: Add release notes to /docs for release of 0.27 git-subtree-dir: docs git-subtree-split: 32356e4eabe357ae914f4d1d59e8ae31ce936723
150 lines
No EOL
5.1 KiB
Markdown
150 lines
No EOL
5.1 KiB
Markdown
---
|
||
title: Add Your Hugo Theme to the Showcase
|
||
linktitle: Themes
|
||
description: If you've built a Hugo theme and want to contribute back to the Hugo Community, add your theme to the Hugo Showcase.
|
||
date: 2017-02-01
|
||
publishdate: 2017-02-01
|
||
lastmod: 2017-02-27
|
||
categories: [contribute]
|
||
keywords: [contribute,themes,design]
|
||
authors: [digitalcraftsman]
|
||
menu:
|
||
docs:
|
||
parent: "contribute"
|
||
weight: 30
|
||
weight: 30
|
||
sections_weight: 30
|
||
draft: false
|
||
aliases: [/contribute/theme/]
|
||
wip: true
|
||
toc: true
|
||
---
|
||
|
||
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`.
|
||
|
||
{{% note %}}
|
||
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.
|
||
{{% /note %}}
|
||
|
||
See the [Hugo Artist theme's exampleSite][artistexample] for a good example.
|
||
|
||
{{% note %}}
|
||
Please make your example site's content is as neutral as possible. We hope this goes without saying.
|
||
{{% /note %}}
|
||
|
||
## 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][themeissuenew] 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:
|
||
|
||
{{< code file="theme.toml" download="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 = ""
|
||
{{< /code >}}
|
||
|
||
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"
|
||
```
|
||
|
||
{{% note %}}
|
||
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`.
|
||
{{% /note %}}
|
||
|
||
### 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
|
||
* <THEMEDIR>/images/screenshot.png</code>
|
||
* <THEMEDIR>/images/tn.png</code>
|
||
|
||
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:
|
||
|
||
{{< code file="README.md" download="README.md" >}}
|
||
|
||
# Theme Title
|
||
|
||
**Need input from @digitalcraftsman on what could be added to this file.**
|
||
|
||
|
||
|
||
|
||
{{< /code >}}
|
||
|
||
{{% note "Screenshots in your `README.md`"%}}
|
||
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](http://themes.gohugo.io/). Therefore, browsers will not be able to display screenshots on the theme site under the given (relative) path.
|
||
{{% /note %}}
|
||
|
||
[artistexample]: https://github.com/digitalcraftsman/hugo-artists-theme/tree/master/exampleSite
|
||
[themeissuenew]: https://github.com/gohugoio/hugoThemes/issues/new |