mirror of
https://github.com/gohugoio/hugo.git
synced 2024-05-11 05:54:58 +00:00
docs: Remove
Docs site is moved to https://github.com/gohugoio/hugoDocs Will be re-added here as a Git submodule.
This commit is contained in:
Bjørn Erik Pedersen
@@ -1,78 +0,0 @@
|
||||
---
|
||||
lastmod: 2015-08-04
|
||||
date: 2014-05-12T10:09:17Z
|
||||
menu:
|
||||
main:
|
||||
parent: themes
|
||||
next: /templates/overview
|
||||
prev: /themes/customizing
|
||||
title: Creating a Theme
|
||||
weight: 50
|
||||
---
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
## Theme Components
|
||||
|
||||
A theme consists of templates and static assets such as javascript and css
|
||||
files. Themes can also optionally provide [archetypes](/content/archetypes/)
|
||||
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
|
||||
|
||||
The default list file layout is located at `layouts/_default/list.html`.
|
||||
|
||||
### Partial Templates
|
||||
|
||||
Theme creators should liberally use [partial templates](/templates/partials/)
|
||||
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.
|
||||
|
||||
### 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
|
||||
|
||||
If your theme makes use of specific keys in the front matter, it is a good idea
|
||||
to provide an archetype for each content type you have. Archetypes follow the
|
||||
[guidelines provided](/content/archetypes/).
|
||||
|
||||
|
||||
### Generator meta tag
|
||||
|
||||
With a growing community around Hugo we recommend theme creators to include the [Generator meta tag]({{< relref "templates/variables.md#hugo-variables" >}}) with `.Hugo.Generator` in the `<head>` of your HTML code. The output might looks like `<meta name="generator" content="Hugo 0.13" />` and helps us to analyse the usage and popularity of Hugo.
|
||||
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
lastmod: 2015-08-04
|
||||
date: 2014-05-12T10:09:34Z
|
||||
menu:
|
||||
main:
|
||||
parent: themes
|
||||
next: /themes/creation
|
||||
prev: /themes/usage
|
||||
title: Customizing a Theme
|
||||
weight: 40
|
||||
toc: true
|
||||
---
|
||||
|
||||
_The following are key concepts for Hugo site customization. Hugo permits you to **supplement or override** any theme template or static file, with files in your working directory._
|
||||
|
||||
_When you use a theme cloned from its git repository, you do not edit the theme's files directly. Rather, you override them as per the following:_
|
||||
|
||||
## Replace Static Files
|
||||
|
||||
For including a different file than what the theme ships with. For example, if you would like to use a more recent version of jQuery than what the theme happens to include, simply place an identically-named file in the same relative location but in your working directory.
|
||||
|
||||
For example, if the theme has jQuery 1.6 in:
|
||||
|
||||
/themes/themename/static/js/jquery.min.js
|
||||
|
||||
... you would simply place your file in the same relative path, but in the root of your working folder:
|
||||
|
||||
/static/js/jquery.min.js
|
||||
|
||||
## Replace a single template file
|
||||
|
||||
Anytime Hugo looks for a matching template, it will first check the working directory before looking in the theme directory. If you would like to modify a template, simply create that template in your local `layouts` directory.
|
||||
|
||||
In the [template documentation](/templates/overview/) _each different template type explains the rules it uses to determine which template to use_. Read and understand these rules carefully.
|
||||
|
||||
This is especially helpful when the theme creator used [partial templates](/templates/partials/). These partial templates are perfect for easy injection into the theme with minimal maintenance to ensure future compatibility.
|
||||
|
||||
For example:
|
||||
|
||||
/themes/themename/layouts/_default/single.html
|
||||
|
||||
... would be overridden by:
|
||||
|
||||
/layouts/_default/single.html
|
||||
|
||||
**Warning**: This only works for templates that Hugo "knows about" (that follow its convention for folder structure and naming). If the theme imports template files in a creatively-named directory, Hugo won’t know to look for the local `/layouts` first.
|
||||
|
||||
## Replace an archetype
|
||||
|
||||
If the archetype that ships with the theme for a given content type (or all content types) doesn’t fit with how you are using the theme, feel free to copy it to your `/archetypes` directory and make modifications as you see fit.
|
||||
|
||||
## Beware of the default
|
||||
|
||||
**Default** is a very powerful force in Hugo, especially as it pertains to overwriting theme files. If a default is located in the local archetype directory or `/layouts/_default/` directory, it will be used instead of any of the similar files in the theme.
|
||||
|
||||
It is usually better to override specific files rather than using the default in your working directory.
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
lastmod: 2015-10-10
|
||||
date: 2014-05-12T10:09:49Z
|
||||
menu:
|
||||
main:
|
||||
parent: themes
|
||||
next: /themes/usage
|
||||
prev: /themes/overview
|
||||
title: Installing Themes
|
||||
weight: 20
|
||||
---
|
||||
|
||||
Community-contributed [Hugo themes](http://themes.gohugo.io/), showcased
|
||||
at [themes.gohugo.io](//themes.gohugo.io/), are hosted in a centralized
|
||||
GitHub repository. The [Hugo Themes Repo](https://github.com/gohugoio/hugoThemes)
|
||||
itself at [github.com/gohugoio/hugoThemes](https://github.com/gohugoio/hugoThemes) is
|
||||
really a meta repository which contains pointers to set of contributed themes.
|
||||
|
||||
## Installing all themes
|
||||
|
||||
If you would like to install all of the available Hugo themes, simply
|
||||
clone the entire repository from within your working directory. Depending
|
||||
on your internet connection the download of all themes might take a while.
|
||||
|
||||
> **NOTE:** Make sure you've installed [Git](https://git-scm.com/) on your computer.
|
||||
Otherwise you will not be able to clone the theme repositories.
|
||||
|
||||
```bash
|
||||
$ git clone --depth 1 --recursive https://github.com/gohugoio/hugoThemes.git themes
|
||||
```
|
||||
Before you use a theme, remove the .git folder in that theme's root folder. Otherwise, this will cause problem if you deploy using Git.
|
||||
|
||||
## Installing a specific theme
|
||||
|
||||
Switch into the `themes` directory and download a theme by replacing `URL_TO_THEME`
|
||||
with the URL of the theme repository, e.g. `https://github.com/spf13/hyde`:
|
||||
|
||||
$ cd themes
|
||||
$ git clone URL_TO_THEME
|
||||
|
||||
Alternatively, you can download the theme as `.zip` file and extract it in the
|
||||
`themes` directory.
|
||||
|
||||
**NOTE:** Please have a look at the `README.md` file that is shipped with all themes.
|
||||
It might contain further instructions that are required to setup the theme, e.g. copying
|
||||
an example configuration file.
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
lastmod: 2015-10-10
|
||||
date: 2014-05-12T10:03:52Z
|
||||
menu:
|
||||
main:
|
||||
parent: themes
|
||||
next: /themes/installing
|
||||
prev: /content/example
|
||||
title: Themes Overview
|
||||
weight: 10
|
||||
---
|
||||
|
||||
Hugo provides a robust theming system which is simple, yet capable of producing
|
||||
even the most complicated websites.
|
||||
|
||||
The Hugo community has created [a wide variety of beautiful themes](//themes.gohugo.io/), as demoed at [themes.gohugo.io](//themes.gohugo.io/),
|
||||
ready for using in your own site.
|
||||
|
||||
Hugo themes have been designed to be the perfect balance between
|
||||
simplicity and functionality. Hugo themes are powered by the excellent
|
||||
Go template library. If you are new to Go templates, see our [primer on
|
||||
Go templates](/templates/go-templates/).
|
||||
|
||||
Hugo themes support all modern features you come to expect. They are
|
||||
structured in such a way to eliminate code duplication. Themes are also
|
||||
designed to be very easy to customize while retaining the ability to
|
||||
maintain upgradeability as the upstream theme changes.
|
||||
|
||||
Hugo currently doesn’t ship with a “default” theme, allowing the user to
|
||||
pick whichever theme best suits their project.
|
||||
|
||||
We hope you will find Hugo themes perfect for your site.
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
lastmod: 2015-01-27
|
||||
date: 2014-05-12T10:09:27Z
|
||||
menu:
|
||||
main:
|
||||
parent: themes
|
||||
next: /themes/customizing
|
||||
prev: /themes/installing
|
||||
title: Using a Theme
|
||||
weight: 30
|
||||
---
|
||||
|
||||
Please make certain you have installed the themes you want to use in the
|
||||
`/themes` directory.
|
||||
|
||||
To use a theme for a site, execute Hugo with the following parameter:
|
||||
|
||||
hugo -t ThemeName
|
||||
|
||||
or add this line to your site configuration:
|
||||
|
||||
theme: "ThemeName"
|
||||
|
||||
The *ThemeName* must match the name of the directory inside `/themes`.
|
||||
|
||||
Hugo will then apply the theme first, then apply anything that is in the local
|
||||
directory. To learn more, go to [customizing themes](/themes/customizing/).
|
||||
Reference in New Issue
Block a user