diff --git a/content/en/configuration/module.md b/content/en/configuration/module.md index 988a25a75..328a4d76b 100644 --- a/content/en/configuration/module.md +++ b/content/en/configuration/module.md @@ -7,6 +7,8 @@ keywords: [] aliases: [/hugo-modules/configuration/] --- +{{% include "/_common/gomodules-info.md" %}} + ## Top-level options This is the default configuration: @@ -61,8 +63,6 @@ export HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.." export HUGO_MODULE_WORKSPACE="/my/hugo.work" ``` -{{% include "/_common/gomodules-info.md" %}} - ## Hugo version You can specify a required Hugo version for your module in the `module` section. Users will then receive a warning if their Hugo version is incompatible. @@ -116,30 +116,30 @@ version : {{< new-in 0.150.0 />}} : If set to a [version query](https://go.dev/ref/mod#version-queries), this import becomes a direct dependency, in contrast to dependencies managed by Go Modules. See [this issue](https://github.com/gohugoio/hugo/pull/13966) for more information. -{{% include "/_common/gomodules-info.md" %}} - ## Mounts -Before Hugo v0.56.0, custom component paths could only be configured by setting [`archetypeDir`], [`assetDir`], [`contentDir`], [`dataDir`], [`i18nDir`], [`layoutDi`], or [`staticDir`] in the site configuration. Module mounts offer greater flexibility than these legacy settings, but -you cannot use both. +{{% glossary-term mount %}} + +> [!important] +> If you define one or more mounts to map a file system path to a component path, do not use these legacy configuration settings: [`archetypeDir`], [`assetDir`], [`contentDir`], [`dataDir`], [`i18nDir`], [`layoutDir`], or [`staticDir`]. [`archetypeDir`]: /configuration/all/ [`assetDir`]: /configuration/all/ [`contentDir`]: /configuration/all/ [`dataDir`]: /configuration/all/ [`i18nDir`]: /configuration/all/ -[`layoutDi`]: /configuration/all/ +[`layoutDir`]: /configuration/all/ [`staticDir`]: /configuration/all/ -> [!note] -> If you use module mounts do not use the legacy settings. - ### Default mounts -> [!note] -> Adding a new mount to a target root will cause the existing default mount for that root to be ignored. If you still need the default mount, you must explicitly add it along with the new mount. +Within a project, if you define a mount to map a file system path to a component path, the corresponding default mount for that component will be removed. This action essentially overwrites the standard, automatic mapping for that specific component with your custom one. -The are the default mounts: +Within a module, if you define a mount to map a file system path to a component path, all of the default mounts will be removed. Defining a mount at the module level is a more sweeping change, causing all default mappings within that module to be discarded. + +In either case, if you still need one of the default mounts, you must explicitly add it along with the new mount. Because custom mounts override defaults, any necessary default mappings must be re-added manually after you introduce your custom configuration. + +These are the default mounts: {{< code-toggle config=module.mounts />}} @@ -147,7 +147,7 @@ source : (`string`) The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative. target -: (`string`) Where the mount will reside within Hugo's virtual file system. It must begin with one of Hugo's component directories: `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, or `static`. For example, `content/blog`. +: (`string`) Where the mount will reside within Hugo's [unified file system](g). It must begin with one of Hugo's [component](g) directories: archetypes, assets, content, data, i18n, layouts, or static. For example, content/blog. disableWatch : {{< new-in 0.128.0 />}} diff --git a/content/en/quick-reference/glossary/archetype.md b/content/en/quick-reference/glossary/archetype.md index 231089c56..d22fae954 100644 --- a/content/en/quick-reference/glossary/archetype.md +++ b/content/en/quick-reference/glossary/archetype.md @@ -1,6 +1,7 @@ --- title: archetype -details: /content-management/archetypes +params: + reference: /content-management/archetypes/ --- An _archetype_ is a template for new content. diff --git a/content/en/quick-reference/glossary/component.md b/content/en/quick-reference/glossary/component.md new file mode 100644 index 000000000..3c3c0236b --- /dev/null +++ b/content/en/quick-reference/glossary/component.md @@ -0,0 +1,17 @@ +--- +title: component +--- + +A _component_ is a collection of related files, housed within the [_unified file system_](g), that fulfills a specific function in building a Hugo website. These components are categorized into seven types: [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files, and can be defined within the project or provided by [_modules_](g). + + Each component has a dedicated directory within the unified file system: + + Component|Directory within the unified file system + :--|:-- + archetypes|`archetypes` + assets|`assets` + content|`content` + data|`data` + templates|`layouts` + translation tables|`i18n` + static files|`static` diff --git a/content/en/quick-reference/glossary/module.md b/content/en/quick-reference/glossary/module.md index 90c8ff80b..30ec49ea4 100644 --- a/content/en/quick-reference/glossary/module.md +++ b/content/en/quick-reference/glossary/module.md @@ -1,6 +1,5 @@ --- title: module -reference: /hugo-modules/ --- -A _module_ is a packaged combination of [_archetypes_](g), assets, content, data, [_templates_](g), translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site. +A _module_ is a packaged combination of [_components_](g) which may include [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files. A module may be a [_theme_](g), a complete project, or a smaller collection of one or more components. diff --git a/content/en/quick-reference/glossary/mount.md b/content/en/quick-reference/glossary/mount.md new file mode 100644 index 000000000..12a4a6414 --- /dev/null +++ b/content/en/quick-reference/glossary/mount.md @@ -0,0 +1,7 @@ +--- +title: mount +params: + reference: /configuration/module +--- + +A _mount_ is a configuration object that maps a file system path (source) to a [_component_](g) path (target) within Hugo's [_unified file system_](g). diff --git a/content/en/quick-reference/glossary/theme.md b/content/en/quick-reference/glossary/theme.md index 84b9c684a..fca98572d 100644 --- a/content/en/quick-reference/glossary/theme.md +++ b/content/en/quick-reference/glossary/theme.md @@ -2,4 +2,4 @@ title: theme --- -A _theme_ is a packaged combination of [_archetypes_](g), assets, content, data, [_templates_](g), translation tables, static files, or configuration settings. A theme may serve as the basis for a new site, or to augment an existing site. +A _theme_ is a [_module_](g) that delivers a complete set of [components](g) defining a site's layout, presentation, and behavior. While every theme is a module, not every module is a theme. diff --git a/content/en/quick-reference/glossary/translation-table.md b/content/en/quick-reference/glossary/translation-table.md new file mode 100644 index 000000000..a48febb67 --- /dev/null +++ b/content/en/quick-reference/glossary/translation-table.md @@ -0,0 +1,5 @@ +--- +title: translation table +--- + +A _translation table_ is a data file within the `i18n` directory, holding translations for a single language. diff --git a/content/en/quick-reference/glossary/unified-file-system.md b/content/en/quick-reference/glossary/unified-file-system.md new file mode 100644 index 000000000..4d3d779de --- /dev/null +++ b/content/en/quick-reference/glossary/unified-file-system.md @@ -0,0 +1,5 @@ +--- +title: unified file system +--- + +Hugo's _unified file system_ provides a layered view for each of its seven [_component_](g) types: [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files. Project component directories are layered over [_module_](g) component directories. Hugo searches these layers in order to locate files.