github.com/lyeb/hugo@v0.47.1/docs/content/en/contribute/themes.md (about)

     1  ---
     2  title: Add Your Hugo Theme to the Showcase
     3  linktitle: Themes
     4  description: If you've built a Hugo theme and want to contribute back to the Hugo Community, add your theme to the Hugo Showcase.
     5  date: 2017-02-01
     6  publishdate: 2017-02-01
     7  lastmod: 2017-02-27
     8  categories: [contribute]
     9  keywords: [contribute,themes,design]
    10  authors: [digitalcraftsman]
    11  menu:
    12    docs:
    13      parent: "contribute"
    14      weight: 30
    15  weight: 30
    16  sections_weight: 30
    17  draft: false
    18  aliases: [/contribute/theme/]
    19  wip: true
    20  toc: true
    21  ---
    22  
    23  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.
    24  
    25  ## tl;dr
    26  
    27  1. Create your theme using `hugo new theme <THEMENAME>`;
    28  2. Test your theme against <https://github.com/gohugoio/hugoBasicExample> \*
    29  3. Add a `theme.toml` file to the root of the theme with all required metadata
    30  4. Add a descriptive `README.md` to the root of the theme source
    31  5. Add `/images/screenshot.png` and `/images/tn.png`
    32  
    33  \* 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`.
    34  
    35  {{% note %}}
    36  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.
    37  {{% /note %}}
    38  
    39  See the [Hugo Artist theme's exampleSite][artistexample] for a good example.
    40  
    41  {{% note %}}
    42  Please make your example site's content is as neutral as possible. We hope this goes without saying.
    43  {{% /note %}}
    44  
    45  ## Theme Requirements
    46  
    47  In order to add your theme to the Hugo Themes Showcase, the following requirements need to be met:
    48  
    49  1. `theme.toml` with all required fields
    50  2. Images for thumbnail and screenshot
    51  3. A good README file instructions for users
    52  4. Addition to the hugoThemes GitHub repository
    53  
    54  ### Add Your Theme to the Repo
    55  
    56  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.
    57  
    58  ### Create a `theme.toml` File
    59  
    60  `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:
    61  
    62  {{< code file="theme.toml" download="theme.toml" >}}
    63  name = ""
    64  license = "MIT"
    65  licenselink = "https://github.com/<YOURNAME>/<YOURTHEME>/blob/master/LICENSE.md"
    66  description = ""
    67  homepage = "https://example.com/"
    68  tags = []
    69  features = []
    70  min_version = 0.19
    71  
    72  [author]
    73    name = ""
    74    homepage = ""
    75  
    76  # If porting an existing theme
    77  [original]
    78    name = ""
    79    homepage = ""
    80    repo = ""
    81  {{< /code >}}
    82  
    83  The following fields are required:
    84  
    85  ```
    86  name = "Hyde"
    87  license = "MIT"
    88  licenselink = "https://github.com/spf13/hyde/blob/master/LICENSE.md"
    89  description = "An elegant open source and mobile first theme"
    90  homepage = "http://siteforthistheme.com/"
    91  tags = ["blog", "company"]
    92  features = ["blog"]
    93  min_version = 0.13
    94  
    95  [author]
    96      name = "spf13"
    97      homepage = "http://spf13.com/"
    98  
    99  # If porting an existing theme
   100  [original]
   101      author = "mdo"
   102      homepage = "http://hyde.getpoole.com/"
   103      repo = "https://www.github.com/mdo/hyde"
   104  ```
   105  
   106  {{% note %}}
   107  1. This is different from the `theme.toml` file created by `hugo new theme` in Hugo versions before v0.14.
   108  2. Only `theme.toml` is accepted; ie. not `theme.yaml` and `theme.json`.
   109  {{% /note %}}
   110  
   111  ### Images
   112  
   113  Screenshots are used for previews in the Hugo Theme Gallery. Make sure that they have the right dimensions:
   114  
   115  * Thumbnail should be 900px × 600px
   116  * Screenshot should be 1500px × 1000px
   117  * Media must be located in
   118      * <THEMEDIR>/images/screenshot.png</code>
   119      * <THEMEDIR>/images/tn.png</code>
   120  
   121  Additional media may be provided in the same directory.
   122  
   123  ### Create a README File
   124  
   125  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
   126  
   127  1. Content for your theme's details page at <https://themes.gohugo.io>
   128  2. General information about the theme in your GitHub repository (i.e., it's usual purpose)
   129  
   130  #### Example `README.md`
   131  
   132  You can download the following `README.md` as an outline:
   133  
   134  {{< code file="README.md" download="README.md" >}}
   135  
   136  # Theme Title
   137  
   138  **Need input from @digitalcraftsman on what could be added to this file.**
   139  
   140  
   141  
   142  
   143  {{< /code >}}
   144  
   145  {{% note "Screenshots in your `README.md`"%}}
   146  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.
   147  {{% /note %}}
   148  
   149  [artistexample]: https://github.com/digitalcraftsman/hugo-artists-theme/tree/master/exampleSite
   150  [themeissuenew]: https://github.com/gohugoio/hugoThemes/issues/new