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
80 lines
No EOL
3.7 KiB
Markdown
80 lines
No EOL
3.7 KiB
Markdown
---
|
||
title: Customize a Theme
|
||
linktitle: Customize a Theme
|
||
description: Customize a theme by overriding theme layouts and static assets in your top-level project directories.
|
||
date: 2017-02-01
|
||
publishdate: 2017-02-01
|
||
lastmod: 2017-02-01
|
||
categories: [themes]
|
||
keywords: [themes, source, organization, directories]
|
||
menu:
|
||
docs:
|
||
parent: "themes"
|
||
weight: 20
|
||
weight: 20
|
||
sections_weight: 20
|
||
draft: false
|
||
aliases: [/themes/customize/]
|
||
toc: true
|
||
wip: true
|
||
---
|
||
|
||
The following are key concepts for Hugo site customization with themes. Hugo permits you to supplement *or* override any theme template or static file with files in your working directory.
|
||
|
||
{{% note %}}
|
||
When you use a theme cloned from its git repository, do not edit the theme's files directly. Instead, theme customization in Hugo is a matter of *overriding* the templates made available to you in a theme. This provides the added flexibility of tweaking a theme to meet your needs while staying current with a theme's upstream.
|
||
{{% /note %}}
|
||
|
||
## Override Static Files
|
||
|
||
There are times where you want to include static assets that differ from versions of the same asset that ships with a theme.
|
||
|
||
For example, a theme may use jQuery 1.8 in the following location:
|
||
|
||
```
|
||
/themes/<THEME>/static/js/jquery.min.js
|
||
```
|
||
|
||
You want to replace the version of jQuery that ships with the theme with the newer `jquery-3.1.1.js`. The easiest way to do this is to replace the file *with a file of the same name* in the same relative path in your project's root. Therefore, change `jquery-3.1.1.js` to `jquery.min.js` so that it is *identical* to the theme's version and place the file here:
|
||
|
||
```
|
||
/static/js/jquery.min.js
|
||
```
|
||
|
||
## Override Template Files
|
||
|
||
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.
|
||
|
||
The [template lookup order][lookup] explains the rules Hugo uses to determine which template to use for a given piece of content. Read and understand these rules carefully.
|
||
|
||
This is especially helpful when the theme creator used [partial templates][partials]. These partial templates are perfect for easy injection into the theme with minimal maintenance to ensure future compatibility.
|
||
|
||
For example:
|
||
|
||
```
|
||
/themes/<THEME>/layouts/_default/single.html
|
||
```
|
||
|
||
Would be overwritten by
|
||
|
||
```
|
||
/layouts/_default/single.html
|
||
```
|
||
|
||
{{% warning %}}
|
||
This only works for templates that Hugo "knows about" (i.e., that follow its convention for folder structure and naming). If a theme imports template files in a creatively named directory, Hugo won’t know to look for the local `/layouts` first.
|
||
{{% /warning %}}
|
||
|
||
## Override Archetypes
|
||
|
||
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.
|
||
|
||
{{% warning "Beware of `layouts/_default`" %}}
|
||
The `_default` directory is a very powerful force in Hugo, especially as it pertains to overwriting theme files. If a default file is located in the local [archetypes](/content-management/archetypes/) or layout directory (i.e., `archetypes/default.md` or `/layouts/_default/*.html`, respectively), it will override the file of the same name in the corresponding theme directory (i.e., `themes/<THEME>/archetypes/default.md` or `themes/<THEME>/layout/_defaults/*.html`, respectively).
|
||
|
||
It is usually better to override specific files; i.e. rather than using `layouts/_default/*.html` in your working directory.
|
||
{{% /warning %}}
|
||
|
||
[archetypes]: /content-management/archetypes/
|
||
[lookup]: /templates/lookup-order/
|
||
[partials]: /templates/partials/ |