2014-05-29 18:42:05 -04:00
|
|
|
---
|
|
|
|
|
date: 2014-05-12T10:09:17Z
|
|
|
|
|
menu:
|
|
|
|
|
main:
|
|
|
|
|
parent: themes
|
|
|
|
|
next: /templates/overview
|
|
|
|
|
prev: /themes/customizing
|
|
|
|
|
title: Creating a Theme
|
|
|
|
|
weight: 50
|
|
|
|
|
---
|
2014-05-27 18:32:57 -04:00
|
|
|
|
|
|
|
|
Hugo has the ability to create a new theme in your themes directory for you
|
|
|
|
|
using the `hugo new` command.
|
|
|
|
|
|
|
|
|
|
`hugo new theme [name]`
|
|
|
|
|
|
|
|
|
|
This command will initialize all of the files and directories a basic theme
|
2014-08-31 07:08:36 -04:00
|
|
|
would need. Hugo themes are written in the Go template language. If you are new
|
|
|
|
|
to Go, the [Go template primer](/layout/go-templates/) will help you get started.
|
2014-05-27 18:32:57 -04:00
|
|
|
|
|
|
|
|
## Theme Components
|
|
|
|
|
|
|
|
|
|
A theme consists of templates and static assets such as javascript and css
|
2015-01-27 21:17:09 -05:00
|
|
|
files. Themes can also optionally provide [archetypes](/content/archetypes/)
|
2014-05-27 18:32:57 -04:00
|
|
|
which are archetypal content types used by the `hugo new` command.
|
|
|
|
|
|
|
|
|
|
### Layouts
|
|
|
|
|
|
|
|
|
|
Hugo is built around the concept that things should be as simple as possible.
|
|
|
|
|
Fundamentally website content is displayed in two different ways, a single
|
|
|
|
|
piece of content and a list of content items. With Hugo a theme layout starts
|
|
|
|
|
with the defaults. As additional layouts are defined they are used for the
|
|
|
|
|
content type or section they apply to. This keeps layouts simple, but permits
|
|
|
|
|
a large amount of flexibility.
|
|
|
|
|
|
|
|
|
|
### Single Content
|
|
|
|
|
|
|
|
|
|
The default single file layout is located at `layouts/_default/single.html`.
|
|
|
|
|
|
|
|
|
|
### List of Contents
|
|
|
|
|
|
2014-12-04 11:26:12 -05:00
|
|
|
The default list file layout is located at `layouts/_default/list.html`.
|
2014-05-27 18:32:57 -04:00
|
|
|
|
2014-06-06 16:15:19 -04:00
|
|
|
### Partial Templates
|
|
|
|
|
|
2015-01-27 21:17:09 -05:00
|
|
|
Theme creators should liberally use [partial templates](/templates/partials/)
|
2014-06-06 16:15:19 -04:00
|
|
|
throughout their theme files. Not only is a good DRY practice to include shared
|
|
|
|
|
code, but partials are a special template type that enables the themes end user
|
|
|
|
|
to be able to overwrite just a small piece of a file or inject code into the
|
|
|
|
|
theme from their local /layouts. These partial templates are perfect for easy
|
|
|
|
|
injection into the theme with minimal maintenance to ensure future
|
|
|
|
|
compatibility.
|
2014-05-27 18:32:57 -04:00
|
|
|
|
|
|
|
|
### Static
|
|
|
|
|
|
|
|
|
|
Everything in the static directory will be copied directly into the final site
|
|
|
|
|
when rendered. No structure is provided here to enable complete freedom. It is
|
|
|
|
|
common to organize the static content into
|
|
|
|
|
|
|
|
|
|
/css
|
|
|
|
|
/js
|
|
|
|
|
/img
|
|
|
|
|
|
|
|
|
|
The actual structure is entirely up to you, the theme creator, on how you would like to organize your files.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Archetypes
|
|
|
|
|
|
2015-01-27 21:17:09 -05:00
|
|
|
If your theme makes use of specific keys in the front matter, it is a good idea
|
2014-05-27 18:32:57 -04:00
|
|
|
to provide an archetype for each content type you have. Archetypes follow the
|
2015-01-27 21:17:09 -05:00
|
|
|
[guidelines provided](/content/archetypes/).
|
2014-05-27 18:32:57 -04:00
|
|
|
|
