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
3.7 KiB
| title | linktitle | description | date | publishdate | lastmod | categories | keywords | menu | weight | sections_weight | draft | aliases | toc | wip | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Customize a Theme | Customize a Theme | Customize a theme by overriding theme layouts and static assets in your top-level project directories. | 2017-02-01 | 2017-02-01 | 2017-02-01 |
|
|
|
20 | 20 | false |
|
true | 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 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. 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 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 %}}