mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-27 22:09:53 +02:00
Merge commit '83bef6955e014d40c0f00db9cebe09113154e999'
This commit is contained in:
Bjørn Erik Pedersen
150
docs/content/en/contribute/themes.md
Normal file
150
docs/content/en/contribute/themes.md
Normal file
@@ -0,0 +1,150 @@
|
||||
---
|
||||
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/gohugoio/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` and `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
|
||||
Reference in New Issue
Block a user