mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-07 20:30:36 -05:00
docs: Add Hugo Modules docs
This commit is contained in:
Bjørn Erik Pedersen
parent
e5f2299741
commit
77bf2991b1
12 changed files with 314 additions and 529 deletions
299
docs/config.toml
299
docs/config.toml
|
|
@ -111,302 +111,3 @@ resampleFilter = "CatmullRom"
|
|||
quality = 75
|
||||
|
||||
anchor = "smart"
|
||||
|
||||
|
||||
## As of v0.20, all content files include a default "categories" value that's the same as the section. This was a cheap future-proofing method and should/could be changed accordingly.
|
||||
[taxonomies]
|
||||
category = "categories"
|
||||
|
||||
# High level items
|
||||
|
||||
[[menu.docs]]
|
||||
name = "About Hugo"
|
||||
weight = 1
|
||||
identifier = "about"
|
||||
url = "/about/"
|
||||
|
||||
[[menu.docs]]
|
||||
name = "Getting Started"
|
||||
weight = 5
|
||||
identifier = "getting-started"
|
||||
url = "/getting-started/"
|
||||
|
||||
|
||||
[[menu.docs]]
|
||||
name = "Themes"
|
||||
weight = 15
|
||||
identifier = "themes"
|
||||
post = "break"
|
||||
url = "/themes/"
|
||||
|
||||
# Core Menus
|
||||
|
||||
[[menu.docs]]
|
||||
name = "Content Management"
|
||||
weight = 20
|
||||
identifier = "content-management"
|
||||
post = "expanded"
|
||||
url = "/content-management/"
|
||||
|
||||
[[menu.docs]]
|
||||
name = "Templates"
|
||||
weight = 25
|
||||
identifier = "templates"
|
||||
|
||||
url = "/templates/"
|
||||
|
||||
[[menu.docs]]
|
||||
name = "Functions"
|
||||
weight = 30
|
||||
identifier = "functions"
|
||||
url = "/functions/"
|
||||
|
||||
[[menu.docs]]
|
||||
name = "Variables"
|
||||
weight = 35
|
||||
identifier = "variables"
|
||||
url = "/variables/"
|
||||
[[menu.docs]]
|
||||
name = "Hugo Pipes"
|
||||
weight = 36
|
||||
identifier = "pipes"
|
||||
url = "/hugo-pipes/"
|
||||
[[menu.docs]]
|
||||
name = "CLI"
|
||||
weight = 40
|
||||
post = "break"
|
||||
identifier = "commands"
|
||||
url = "/commands/"
|
||||
|
||||
|
||||
|
||||
# LOW LEVEL ITEMS
|
||||
|
||||
|
||||
[[menu.docs]]
|
||||
name = "Troubleshooting"
|
||||
weight = 60
|
||||
identifier = "troubleshooting"
|
||||
url = "/troubleshooting/"
|
||||
|
||||
[[menu.docs]]
|
||||
name = "Tools"
|
||||
weight = 70
|
||||
identifier = "tools"
|
||||
url = "/tools/"
|
||||
|
||||
[[menu.docs]]
|
||||
name = "Hosting & Deployment"
|
||||
weight = 80
|
||||
identifier = "hosting-and-deployment"
|
||||
url = "/hosting-and-deployment/"
|
||||
|
||||
[[menu.docs]]
|
||||
name = "Contribute"
|
||||
weight = 100
|
||||
post = "break"
|
||||
identifier = "contribute"
|
||||
url = "/contribute/"
|
||||
|
||||
#[[menu.docs]]
|
||||
# name = "Tags"
|
||||
# weight = 120
|
||||
# identifier = "tags"
|
||||
# url = "/tags/"
|
||||
|
||||
|
||||
# [[menu.docs]]
|
||||
# name = "Categories"
|
||||
# weight = 140
|
||||
# identifier = "categories"
|
||||
# url = "/categories/"
|
||||
|
||||
######## QUICKLINKS
|
||||
|
||||
[[menu.quicklinks]]
|
||||
name = "Fundamentals"
|
||||
weight = 1
|
||||
identifier = "fundamentals"
|
||||
url = "/tags/fundamentals/"
|
||||
|
||||
|
||||
|
||||
|
||||
######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES
|
||||
|
||||
[[menu.global]]
|
||||
name = "News"
|
||||
weight = 1
|
||||
identifier = "news"
|
||||
url = "/news/"
|
||||
|
||||
[[menu.global]]
|
||||
name = "Docs"
|
||||
weight = 5
|
||||
identifier = "docs"
|
||||
url = "/documentation/"
|
||||
|
||||
[[menu.global]]
|
||||
name = "Themes"
|
||||
weight = 10
|
||||
identifier = "themes"
|
||||
url = "https://themes.gohugo.io/"
|
||||
|
||||
[[menu.global]]
|
||||
name = "Showcase"
|
||||
weight = 20
|
||||
identifier = "showcase"
|
||||
url = "/showcase/"
|
||||
|
||||
# Anything with a weight > 100 gets an external icon
|
||||
[[menu.global]]
|
||||
name = "Community"
|
||||
weight = 150
|
||||
icon = true
|
||||
identifier = "community"
|
||||
post = "external"
|
||||
url = "https://discourse.gohugo.io/"
|
||||
|
||||
|
||||
[[menu.global]]
|
||||
name = "GitHub"
|
||||
weight = 200
|
||||
identifier = "github"
|
||||
post = "external"
|
||||
url = "https://github.com/gohugoio/hugo"
|
||||
|
||||
### LANGUAGES ###
|
||||
|
||||
[languages]
|
||||
[languages.en]
|
||||
contentDir = "content/en"
|
||||
languageName = "English"
|
||||
weight = 1
|
||||
[languages.zh]
|
||||
contentDir = "content/zh"
|
||||
languageName = "中文"
|
||||
weight = 2
|
||||
|
||||
|
||||
### LANGUAGE-SPECIFIC MENUS ###
|
||||
|
||||
# Chinese menus
|
||||
|
||||
[[languages.zh.menu.docs]]
|
||||
name = "关于 Hugo"
|
||||
weight = 1
|
||||
identifier = "about"
|
||||
url = "/zh/about/"
|
||||
|
||||
[[languages.zh.menu.docs]]
|
||||
name = "入门"
|
||||
weight = 5
|
||||
identifier = "getting-started"
|
||||
url = "/zh/getting-started/"
|
||||
|
||||
[[languages.zh.menu.docs]]
|
||||
name = "主题"
|
||||
weight = 15
|
||||
identifier = "themes"
|
||||
post = "break"
|
||||
url = "/zh/themes/"
|
||||
|
||||
# Core languages.zh.menus
|
||||
|
||||
[[languages.zh.menu.docs]]
|
||||
name = "内容管理"
|
||||
weight = 20
|
||||
identifier = "content-management"
|
||||
post = "expanded"
|
||||
url = "/zh/content-management/"
|
||||
|
||||
[[languages.zh.menu.docs]]
|
||||
name = "模板"
|
||||
weight = 25
|
||||
identifier = "templates"
|
||||
url = "/zh/templates/"
|
||||
|
||||
[[languages.zh.menu.docs]]
|
||||
name = "函数"
|
||||
weight = 30
|
||||
identifier = "functions"
|
||||
url = "/zh/functions/"
|
||||
|
||||
[[languages.zh.menu.docs]]
|
||||
name = "变量"
|
||||
weight = 35
|
||||
identifier = "variables"
|
||||
url = "/zh/variables/"
|
||||
|
||||
[[languages.zh.menu.docs]]
|
||||
name = "CLI"
|
||||
weight = 40
|
||||
post = "break"
|
||||
identifier = "commands"
|
||||
url = "/commands/"
|
||||
|
||||
# LOW LEVEL ITEMS
|
||||
[[languages.zh.menu.docs]]
|
||||
name = "故障排除"
|
||||
weight = 60
|
||||
identifier = "troubleshooting"
|
||||
url = "/zh/troubleshooting/"
|
||||
|
||||
[[languages.zh.menu.docs]]
|
||||
name = "工具"
|
||||
weight = 70
|
||||
identifier = "tools"
|
||||
url = "/zh/tools/"
|
||||
|
||||
[[languages.zh.menu.docs]]
|
||||
name = "托管与部署"
|
||||
weight = 80
|
||||
identifier = "hosting-and-deployment"
|
||||
url = "/zh/hosting-and-deployment/"
|
||||
|
||||
[[languages.zh.menu.docs]]
|
||||
name = "贡献"
|
||||
weight = 100
|
||||
post = "break"
|
||||
identifier = "contribute"
|
||||
url = "/zh/contribute/"
|
||||
|
||||
[[languages.zh.menu.global]]
|
||||
name = "新闻"
|
||||
weight = 1
|
||||
identifier = "news"
|
||||
url = "/zh/news/"
|
||||
|
||||
[[languages.zh.menu.global]]
|
||||
name = "文档"
|
||||
weight = 5
|
||||
identifier = "docs"
|
||||
url = "/zh/documentation/"
|
||||
|
||||
[[languages.zh.menu.global]]
|
||||
name = "主题"
|
||||
weight = 10
|
||||
identifier = "themes"
|
||||
url = "https://themes.gohugo.io/"
|
||||
|
||||
[[languages.zh.menu.global]]
|
||||
name = "作品展示"
|
||||
weight = 20
|
||||
identifier = "showcase"
|
||||
url = "/zh/showcase/"
|
||||
|
||||
# Anything with a weight > 100 gets an external icon
|
||||
[[languages.zh.menu.global]]
|
||||
name = "社区"
|
||||
weight = 150
|
||||
icon = true
|
||||
identifier = "community"
|
||||
post = "external"
|
||||
url = "https://discourse.gohugo.io/"
|
||||
|
||||
[[languages.zh.menu.global]]
|
||||
name = "GitHub"
|
||||
weight = 200
|
||||
identifier = "github"
|
||||
post = "external"
|
||||
url = "https://github.com/gohugoio/hugo"
|
||||
|
|
|
|||
|
|
@ -11,11 +11,11 @@
|
|||
url = "/getting-started/"
|
||||
|
||||
[[docs]]
|
||||
name = "Themes"
|
||||
name = "Hugo Modules"
|
||||
weight = 15
|
||||
identifier = "themes"
|
||||
identifier = "modules"
|
||||
post = "break"
|
||||
url = "/themes/"
|
||||
url = "/hugo-modules/"
|
||||
|
||||
# Core Menus
|
||||
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ hugo --config a.toml,b.toml,c.toml
|
|||
Multiple site config files can be specified as a comma-separated string to the `--config` switch.
|
||||
{{% /note %}}
|
||||
|
||||
TODO: distinct config.toml and others (the root object files)
|
||||
{{< todo >}}TODO: distinct config.toml and others (the root object files){{< /todo >}}
|
||||
|
||||
## Configuration Directory
|
||||
|
||||
|
|
@ -76,10 +76,10 @@ value in parentheses. Users may choose to override those values in their site
|
|||
config file(s).
|
||||
|
||||
archetypeDir ("archetypes")
|
||||
: The directory where Hugo finds archetype files (content templates).
|
||||
: The directory where Hugo finds archetype files (content templates). {{% module-mounts-note %}}
|
||||
|
||||
assetDir ("assets")
|
||||
: The directory where Hugo finds asset files used in [Hugo Pipes](/hugo-pipes/).
|
||||
: The directory where Hugo finds asset files used in [Hugo Pipes](/hugo-pipes/). {{% module-mounts-note %}}
|
||||
|
||||
baseURL
|
||||
: Hostname (and path) to the root, e.g. http://bep.is/
|
||||
|
|
@ -103,10 +103,10 @@ canonifyURLs (false)
|
|||
: Enable to turn relative URLs into absolute.
|
||||
|
||||
contentDir ("content")
|
||||
: The directory from where Hugo reads content files.
|
||||
: The directory from where Hugo reads content files. {{% module-mounts-note %}}
|
||||
|
||||
dataDir ("data")
|
||||
: The directory from where Hugo reads data files.
|
||||
: The directory from where Hugo reads data files. {{% module-mounts-note %}}
|
||||
|
||||
defaultContentLanguage ("en")
|
||||
: Content without language indicator will default to this language.
|
||||
|
|
@ -190,6 +190,9 @@ menu
|
|||
metaDataFormat ("toml")
|
||||
: Front matter meta-data format. Valid values: `"toml"`, `"yaml"`, or `"json"`.
|
||||
|
||||
module
|
||||
: Module config see [Module Config](/hugo-modules/configuration/).
|
||||
|
||||
newContentEditor ("")
|
||||
: The editor to use when creating new content.
|
||||
|
||||
|
|
@ -245,7 +248,7 @@ sitemap
|
|||
: Default [sitemap configuration](/templates/sitemap-template/#configure-sitemap-xml).
|
||||
|
||||
staticDir ("static")
|
||||
: A directory or a list of directories from where Hugo reads [static files][static-files].
|
||||
: A directory or a list of directories from where Hugo reads [static files][static-files]. {{% module-mounts-note %}}
|
||||
|
||||
summaryLength (70)
|
||||
: The length of text in words to show in a [`.Summary`](/content-management/summaries/#hugo-defined-automatic-summary-splitting).
|
||||
|
|
@ -470,9 +473,11 @@ maxAge = -1
|
|||
[caches.assets]
|
||||
dir = ":resourceDir/_gen"
|
||||
maxAge = -1
|
||||
[caches.modules]
|
||||
dir = ":cacheDir/modules"
|
||||
maxAge = -1
|
||||
```
|
||||
|
||||
|
||||
You can override any of these cache setting in your own `config.toml`.
|
||||
|
||||
### The keywords explained
|
||||
|
|
|
|||
24
docs/content/en/hugo-modules/_index.md
Normal file
24
docs/content/en/hugo-modules/_index.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
title: Hugo Modules
|
||||
linktitle: Hugo Modules Overview
|
||||
description: How to use Hugo Modules.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
menu:
|
||||
docs:
|
||||
parent: "modules"
|
||||
weight: 01
|
||||
weight: 01
|
||||
sections_weight: 01
|
||||
categories: [hugo modules]
|
||||
keywords: [themes,modules]
|
||||
draft: false
|
||||
aliases: [/themes/overview/,/themes/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
**Hugo Modules** are the core building blocks in Hugo. A _module_ can be your main project or a smaller module providing one or more of the 7 component types defined in Hugo: **static**, **content**, **layouts**, **data**, **assets**, **i18n**, and **archetypes**.
|
||||
|
||||
You can combine modules in any combination you like, and even mount directories from non-Hugo projects, forming a big, virtual union file system.
|
||||
|
||||
|
||||
126
docs/content/en/hugo-modules/configuration.md
Normal file
126
docs/content/en/hugo-modules/configuration.md
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
---
|
||||
title: Configure Modules
|
||||
linktitle: Configure Modules
|
||||
description: This page describes the configuration options for a module.
|
||||
date: 2019-07-24
|
||||
categories: [hugo modules]
|
||||
keywords: [themes, source, organization, directories]
|
||||
menu:
|
||||
docs:
|
||||
parent: "modules"
|
||||
weight: 10
|
||||
weight: 10
|
||||
sections_weight: 10
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Module Config: Top level
|
||||
|
||||
{{< code-toggle file="config">}}
|
||||
[module]
|
||||
proxy = "direct"
|
||||
noProxy = "none"
|
||||
private = "*.*"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
proxy
|
||||
: Defines the proxy server to use to download remote modules. Default is `direct`, which means "git clone" and similar.
|
||||
|
||||
noProxy
|
||||
: Comma separated glob list matching paths that should not use the proxy configured above.
|
||||
|
||||
private
|
||||
: Comma separated glob list matching paths that should be treated as private.
|
||||
|
||||
Note that the above terms maps directly to their counterparts in Go Modules. Some of these setting may be natural to set as OS environvent variables. To set the proxy server to use, as an example:
|
||||
|
||||
```
|
||||
env HUGO_MODULE_PROXY=https://proxy.example.org hugo
|
||||
```
|
||||
|
||||
{{< gomodules-info >}}
|
||||
|
||||
## Module Config: hugoVersion
|
||||
|
||||
If your module requires a particular version of Hugo to work, you can indicate that in the `module` section and the user will be warned if using a too old/new version.
|
||||
|
||||
{{< code-toggle file="config">}}
|
||||
[module]
|
||||
[module.hugoVersion]
|
||||
min = ""
|
||||
max = ""
|
||||
extended = false
|
||||
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Any of the above can be omitted.
|
||||
|
||||
min
|
||||
: The minimum Hugo version supported, e.g. `0.55.0`
|
||||
|
||||
max
|
||||
: The maximum Hugo version supported, e.g. `0.55.0`
|
||||
|
||||
extended
|
||||
: Whether the extended version of Hugo is required.
|
||||
|
||||
## Module Config: imports
|
||||
|
||||
{{< code-toggle file="config">}}
|
||||
[module]
|
||||
[[module.imports]]
|
||||
path = "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v"
|
||||
ignoreConfig = false
|
||||
disable = false
|
||||
[[module.imports]]
|
||||
path = "my-shortcodes"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
path
|
||||
: Can be either a valid Go Module module path, e.g. `github.com/gohugoio/myShortcodes`, or the directory name for the module as stored in your themes folder.
|
||||
|
||||
ignoreConfig
|
||||
: If enabled, any module configuration file, e.g. `config.toml`, will not be loaded. Note that this will also stop the loading of any transitive module dependencies.
|
||||
|
||||
disable
|
||||
: Set to `true` to disable the module off while keeping any version info in the `go.*` files.
|
||||
|
||||
{{< gomodules-info >}}
|
||||
|
||||
|
||||
## Module Config: mounts
|
||||
|
||||
{{< code-toggle file="config">}}
|
||||
[module]
|
||||
[[module.mounts]]
|
||||
source="content"
|
||||
target="content"
|
||||
[[module.mounts]]
|
||||
source="static"
|
||||
target="static"
|
||||
[[module.mounts]]
|
||||
source="layouts"
|
||||
target="layouts"
|
||||
[[module.mounts]]
|
||||
source="data"
|
||||
target="data"
|
||||
[[module.mounts]]
|
||||
source="assets"
|
||||
target="assets"
|
||||
[[module.mounts]]
|
||||
source="i18n"
|
||||
target="i18n"
|
||||
[[module.mounts]]
|
||||
source="archetypes"
|
||||
target="archetypes"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
source
|
||||
: The source direcory of the mount. For the main project, this can be either project-relative or absolute and even a symbolic link. For other modules it must be project-relative.
|
||||
|
||||
target
|
||||
: Where it should be mounted into Hugo's virtual filesystem. It must start with one of Hugo's component folders: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, or `archetypes`. E.g. `content/blog`.
|
||||
|
||||
lang
|
||||
: The language code, e.g. "en". Only relevant for `content` mounts, and `static` mounts when in multihost mode.
|
||||
|
||||
|
|
@ -3,19 +3,22 @@ title: Theme Components
|
|||
linktitle: Theme Components
|
||||
description: Hugo provides advanced theming support with Theme Components.
|
||||
date: 2017-02-01
|
||||
categories: [themes]
|
||||
categories: [hugo modules]
|
||||
keywords: [themes, theme, source, organization, directories]
|
||||
menu:
|
||||
docs:
|
||||
parent: "themes"
|
||||
weight: 20
|
||||
weight: 20
|
||||
sections_weight: 20
|
||||
parent: "modules"
|
||||
weight: 50
|
||||
weight: 50
|
||||
sections_weight: 50
|
||||
draft: false
|
||||
aliases: [/themes/customize/,/themes/customizing/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{% note %}}
|
||||
This section contain information that may be outdated and is in the process of being rewritten.
|
||||
{{% /note %}}
|
||||
Since Hugo `0.42` a project can configure a theme as a composite of as many theme components you need:
|
||||
|
||||
{{< code-toggle file="config">}}
|
||||
122
docs/content/en/hugo-modules/use-modules.md
Normal file
122
docs/content/en/hugo-modules/use-modules.md
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
---
|
||||
title: Use Hugo Modules
|
||||
linktitle: Use Hugo Modules
|
||||
description: How to use Hugo Modules to build and manage your site.
|
||||
date: 2019-07-24
|
||||
categories: [hugo modules]
|
||||
keywords: [install, themes, source, organization, directories,usage,modules]
|
||||
menu:
|
||||
docs:
|
||||
parent: "modules"
|
||||
weight: 20
|
||||
weight: 20
|
||||
sections_weight: 20
|
||||
draft: false
|
||||
aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
{{% gomodules-info %}}
|
||||
|
||||
|
||||
|
||||
## Initialize a New Module
|
||||
|
||||
Use `hugo mod init` to initialize a new Hugo Module. If it fails to guess the module path, you must provide it as an argument, e.g.:
|
||||
|
||||
```bash
|
||||
hugo mod init github.com/gohugoio/myShortcodes
|
||||
```
|
||||
|
||||
|
||||
Also see the [CLI Doc](/commands/hugo_mod_init/).
|
||||
|
||||
## Update Modules
|
||||
|
||||
Modules will be downloaded and added when you add them as imports to your configuration, see [Module Imports](/hugo-modules/configuration/#module-config-imports).
|
||||
|
||||
To update or manage versions, you can use `hugo mod get`.
|
||||
|
||||
Some examples:
|
||||
|
||||
### Update All Modules
|
||||
|
||||
```bash
|
||||
hugo mod get -u
|
||||
```
|
||||
### Update One Module
|
||||
|
||||
```bash
|
||||
hugo mod get -u github.com/gohugoio/myShortcodes
|
||||
```
|
||||
### Get a Specific Version
|
||||
|
||||
```bash
|
||||
hugo mod get github.com/gohugoio/myShortcodes@v1.0.7
|
||||
```
|
||||
|
||||
Also see the [CLI Doc](/commands/hugo_mod_get/).
|
||||
|
||||
## Make and test changes in a module
|
||||
|
||||
One way to do local development of a module imported in a project is to add a replace directive to a local directory with the source in `go.mod`:
|
||||
|
||||
```bash
|
||||
github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypartials
|
||||
```
|
||||
|
||||
If you have the `hugo server` running, the configuration will be reloaded and `/Users/bep/hugotestmods/mypartials` put on the watch list.
|
||||
|
||||
|
||||
## Print Dependency Graph
|
||||
|
||||
|
||||
Use `hugo mod graph` from the relevant module directory and it will print the dependency graph, including vendoring, module replacement or disabled status.
|
||||
|
||||
E.g.:
|
||||
|
||||
```
|
||||
hugo mod graph
|
||||
|
||||
github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0
|
||||
github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7
|
||||
github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4
|
||||
github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0
|
||||
DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396
|
||||
github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1
|
||||
github.com/bep/my-modular-site in-themesdir
|
||||
|
||||
```
|
||||
|
||||
Also see the [CLI Doc](/commands/hugo_mod_graph/).
|
||||
|
||||
## Vendor Your Modules
|
||||
|
||||
`hugo mod vendor` will write all the module depencies to a `_vendor` folder, which will then be used for all subsequent builds.
|
||||
|
||||
Note that:
|
||||
|
||||
* You can run `hugo mod vendor` on any level in the module tree.
|
||||
* Vendoring will not store modules stored in your `themes` folder.
|
||||
* Most commands accept a `--ignoreVendor` flag, which will then run as if the none of the `_vendor` folders in the module tree did not exist.
|
||||
|
||||
Also see the [CLI Doc](/commands/hugo_mod_vendor/).
|
||||
|
||||
|
||||
## Tidy go.mod, go.sum
|
||||
|
||||
Run `hugo mod tidy` to remove unused entries in `go.mod` and `go.sum`.
|
||||
|
||||
Also see the [CLI Doc](/commands/hugo_mod_clean/).
|
||||
|
||||
## Clean Module Cache
|
||||
|
||||
Run `hugo mod clean` to delete the entire modules cache.
|
||||
|
||||
Note that you can also configure the `modules` cache with a `maxAge`, see [File Caches](/configuration/#configure-file-caches).
|
||||
|
||||
|
||||
|
||||
Also see the [CLI Doc](/commands/hugo_mod_clean/).
|
||||
|
|
@ -1,26 +0,0 @@
|
|||
---
|
||||
title: Themes
|
||||
linktitle: Themes Overview
|
||||
description: Install, use, and create Hugo themes.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
menu:
|
||||
docs:
|
||||
parent: "themes"
|
||||
weight: 01
|
||||
weight: 01
|
||||
sections_weight: 01
|
||||
categories: [themes]
|
||||
keywords: [themes,introduction,overview]
|
||||
draft: false
|
||||
aliases: [/themes/overview/]
|
||||
toc: false
|
||||
---
|
||||
|
||||
Hugo provides a robust theming system that is easy to implement yet feature complete. You can view the themes created by the Hugo community on the [Hugo themes website][hugothemes].
|
||||
|
||||
Hugo themes are powered by the excellent Go template library and are designed to reduce code duplication. They are easy to both customize and keep in sync with the upstream theme.
|
||||
|
||||
[goprimer]: /templates/introduction/
|
||||
[hugothemes]: http://themes.gohugo.io/
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
---
|
||||
title: Create a Theme
|
||||
linktitle: Create a Theme
|
||||
description: The `hugo new theme` command will scaffold the beginnings of a new theme for you to get you on your way.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [themes]
|
||||
keywords: [themes, source, organization, directories]
|
||||
menu:
|
||||
docs:
|
||||
parent: "themes"
|
||||
weight: 30
|
||||
weight: 30
|
||||
sections_weight: 30
|
||||
draft: false
|
||||
aliases: [/themes/creation/,/tutorials/creating-a-new-theme/]
|
||||
toc: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
{{% warning "Use Absolute Links" %}}
|
||||
If you're creating a theme with plans to share it on the [Hugo Themes website](https://themes.gohugo.io/) please note the following:
|
||||
- If using inline styles you will need to use absolute URLs, for the linked assets to be served properly, e.g. `<div style="background: url('{{ "images/background.jpg" | absURL }}')">`
|
||||
- Make sure not to use a forward slash `/` in the beginning of a `URL`, because it will point to the host root. Your theme's demo will be available in a subdirectory of the Hugo website and in this scenario Hugo will not generate the correct `URL` for theme assets.
|
||||
- If using external CSS and JS from a CDN, make sure to load these assets over `https`. Please do not use relative protocol URLs in your theme's templates.
|
||||
{{% /warning %}}
|
||||
|
||||
Hugo can initialize a new blank theme directory within your existing `themes` using the `hugo new` command:
|
||||
|
||||
```
|
||||
hugo new theme [name]
|
||||
```
|
||||
|
||||
## Theme Folders
|
||||
|
||||
A theme component can provide files in one or more of the following standard Hugo folders:
|
||||
|
||||
layouts
|
||||
: Templates used to render content in Hugo. Also see [Templates Lookup Order](/templates/lookup-order/).
|
||||
|
||||
static
|
||||
: Static files, such as logos, CSS and JavaScript.
|
||||
|
||||
i18n
|
||||
: Language bundles.
|
||||
|
||||
data
|
||||
: Data files.
|
||||
|
||||
archetypes
|
||||
: Content templates used in `hugo new`.
|
||||
|
||||
|
||||
## Theme Configuration File
|
||||
|
||||
A theme component can also provide its own [Configuration File](/getting-started/configuration/), e.g. `config.toml`. There are some restrictions to what can be configured in a theme component, and it is not possible to overwrite settings in the project.
|
||||
|
||||
The following settings can be set:
|
||||
|
||||
* `params` (global and per language)
|
||||
* `menu` (global and per language)
|
||||
* `outputformats` and `mediatypes`
|
||||
|
||||
|
||||
## Theme Description File
|
||||
|
||||
In addition to the configuration file, a theme can also provide a `theme.toml` file that describes the theme, the author and origin etc. See [Add Your Hugo Theme to the Showcase](/contribute/themes/).
|
||||
|
||||
|
||||
{{% note "Use the Hugo Generator Tag" %}}
|
||||
The [`.Hugo.Generator`](/variables/hugo/) tag is included in all themes featured in the [Hugo Themes Showcase](http://themes.gohugo.io). We ask that you include the generator tag in all sites and themes you create with Hugo to help the core team track Hugo's usage and popularity.
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
|
|
@ -1,114 +0,0 @@
|
|||
---
|
||||
title: Install and Use Themes
|
||||
linktitle: Install and Use Themes
|
||||
description: Install and use a theme from the Hugo theme showcase easily through the CLI.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [themes]
|
||||
keywords: [install, themes, source, organization, directories,usage]
|
||||
menu:
|
||||
docs:
|
||||
parent: "themes"
|
||||
weight: 10
|
||||
weight: 10
|
||||
sections_weight: 10
|
||||
draft: false
|
||||
aliases: [/themes/usage/,/themes/installing/]
|
||||
toc: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
{{% note "No Default Theme" %}}
|
||||
Hugo currently doesn’t ship with a “default” theme. This decision is intentional. We leave it up to you to decide which theme best suits your Hugo project.
|
||||
{{% /note %}}
|
||||
|
||||
## Assumptions
|
||||
|
||||
1. You have already [installed Hugo on your development machine][install].
|
||||
2. You have git installed on your machine and you are familiar with basic git usage.
|
||||
|
||||
## Install Themes
|
||||
|
||||
{{< youtube L34JL_3Jkyc >}}
|
||||
|
||||
The community-contributed themes featured on [themes.gohugo.io](//themes.gohugo.io/) are hosted in a [centralized GitHub repository][themesrepo]. The Hugo Themes Repo at <https://github.com/gohugoio/hugoThemes> is really a meta repository that contains pointers to a set of contributed themes.
|
||||
|
||||
{{% warning "Get `git` First" %}}
|
||||
Without [Git](https://git-scm.com/) installed on your computer, none of the following theme instructions will work. Git tutorials are beyond the scope of the Hugo docs, but [GitHub](https://try.github.io/) and [codecademy](https://www.codecademy.com/learn/learn-git) offer free, interactive courses for beginners.
|
||||
{{% /warning %}}
|
||||
|
||||
### Install All Themes
|
||||
|
||||
You can install *all* available Hugo themes by cloning the entire [Hugo Theme repository on GitHub][themesrepo] from within your working directory. Depending on your internet connection the download of all themes might take a while.
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
### Install a Single Theme
|
||||
|
||||
Change into the `themes` directory and download a theme by replacing `URL_TO_THEME` with the URL of the theme repository:
|
||||
|
||||
```
|
||||
cd themes
|
||||
git clone URL_TO_THEME
|
||||
```
|
||||
|
||||
The following example shows how to use the "Hyde" theme, which has its source hosted at <https://github.com/spf13/hyde>:
|
||||
|
||||
{{< code file="clone-theme.sh" >}}
|
||||
cd themes
|
||||
git clone https://github.com/spf13/hyde
|
||||
{{< /code >}}
|
||||
|
||||
Alternatively, you can download the theme as a `.zip` file, unzip the theme contents, and then move the unzipped source into your `themes` directory.
|
||||
|
||||
{{% note "Read the `README`" %}}
|
||||
Always review the `README.md` file that is shipped with a theme. Often, these files contain further instructions required for theme setup; e.g., copying values from an example configuration file.
|
||||
{{% /note %}}
|
||||
|
||||
## Theme Placement
|
||||
|
||||
Please make certain you have installed the themes you want to use in the
|
||||
`/themes` directory. This is the default directory used by Hugo. Hugo comes with the ability to change the themes directory via the [`themesDir` variable in your site configuration][config], but this is not recommended.
|
||||
|
||||
## Use Themes
|
||||
|
||||
Hugo applies the decided theme first and then applies anything that is in the local directory. This allows for easier customization while retaining compatibility with the upstream version of the theme. To learn more, go to [customizing themes][customizethemes].
|
||||
|
||||
### Command Line
|
||||
|
||||
There are two different approaches to using a theme with your Hugo website: via the Hugo CLI or as part of your [site configuration file][config].
|
||||
|
||||
To change a theme via the Hugo CLI, you can pass the `-t` [flag][] when building your site:
|
||||
|
||||
```
|
||||
hugo -t themename
|
||||
```
|
||||
|
||||
Likely, you will want to add the theme when running the Hugo local server, especially if you are going to [customize the theme][customizethemes]:
|
||||
|
||||
```
|
||||
hugo server -t themename
|
||||
```
|
||||
|
||||
### `config` File
|
||||
|
||||
If you've already decided on the theme for your site and do not want to fiddle with the command line, you can add the theme directly to your [site configuration file][config]:
|
||||
|
||||
```
|
||||
theme: themename
|
||||
```
|
||||
|
||||
{{% note "A Note on `themename`" %}}
|
||||
The `themename` in the above examples must match the name of the specific theme directory inside `/themes`; i.e., the directory name (likely lowercase and urlized) rather than the name of the theme displayed in the [Themes Showcase site](http://themes.gohugo.io).
|
||||
{{% /note %}}
|
||||
|
||||
[customizethemes]: /themes/customizing/
|
||||
[flag]: /getting-started/usage/ "See the full list of flags in Hugo's basic usage."
|
||||
[install]: /getting-started/installing/
|
||||
[config]: /getting-started/configuration/ "Learn how to customize your Hugo website configuration file in yaml, toml, or json."
|
||||
[themesrepo]: https://github.com/gohugoio/hugoThemes
|
||||
18
docs/layouts/shortcodes/gomodules-info.html
Normal file
18
docs/layouts/shortcodes/gomodules-info.html
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
|
||||
{{ $text := `
|
||||
Most of the commands for **Hugo Modules** requires a newer version of Go installed (see https://golang.org/dl/) and the relevant VCS client (e.g. Git, see https://git-scm.com/downloads).
|
||||
|
||||
For more information about Go Modules, see:
|
||||
|
||||
* https://github.com/golang/go/wiki/Modules
|
||||
* https://blog.golang.org/using-go-modules
|
||||
` }}
|
||||
|
||||
<aside class="admonition note">
|
||||
<div class="note-icon">
|
||||
{{partial "svg/exclamation.svg" (dict "size" "20px" ) }}
|
||||
</div>
|
||||
<div class="admonition-content">
|
||||
{{- $text | markdownify -}}
|
||||
</div>
|
||||
</aside>
|
||||
1
docs/layouts/shortcodes/module-mounts-note.html
Normal file
1
docs/layouts/shortcodes/module-mounts-note.html
Normal file
|
|
@ -0,0 +1 @@
|
|||
Also see [Module Mounts Config](/hugo-modules/configuration/#module-config-mounts) for an alternative way to configure this directory (from Hugo 0.56).
|
||||
Loading…
Reference in a new issue