modules

Documentation

Overview

Package modules provides a client that can be used to manage Hugo Components, what's referred to as Hugo Modules. Hugo Modules is built on top of Go Modules, but also supports vendoring and components stored directly in the themes dir.

Index

• Constants
• Variables
• func ApplyProjectConfigDefaults(mod Module, cfgs ...config.AllProvider) error
• type Client
  • func NewClient(cfg ClientConfig) *Client
  • func (c *Client) Clean(pattern string) error
  • func (h *Client) Collect() (ModulesConfig, error)
  • func (c *Client) Get(args ...string) error
  • func (c *Client) Graph(w io.Writer) error
  • func (c *Client) Init(path string) error
  • func (c *Client) Tidy() error
  • func (c *Client) Vendor() error
  • func (c *Client) Verify(clean bool) error
• type ClientConfig
• type Config
  • func DecodeConfig(cfg config.Provider) (Config, error)
• type HugoVersion
  • func (v HugoVersion) IsValid() bool
  • func (v HugoVersion) String() string
• type Import
• type Module
• type Modules
• type ModulesConfig
  • func (m ModulesConfig) HasConfigFile() bool
• type Mount
  • func (m Mount) Component() string
  • func (m Mount) ComponentAndName() (string, string)

Constants

const WorkspaceDisabled = "off"

Variables

var DefaultModuleConfig = Config{

	Proxy: "direct",

	NoProxy: "none",

	Private: "*.*",

	Workspace: WorkspaceDisabled,

	Replacements: nil,
}

var ErrNotExist = errors.New("module does not exist")

Functions

func ApplyProjectConfigDefaults

func ApplyProjectConfigDefaults(mod Module, cfgs ...config.AllProvider) error

ApplyProjectConfigDefaults applies default/missing module configuration for the main project.

Types

type Client

type Client struct {

	// Set when Go modules are initialized in the current repo, that is:
	// a go.mod file exists.
	GoModulesFilename string
	// contains filtered or unexported fields
}

Client contains most of the API provided by this package.

func NewClient

func NewClient(cfg ClientConfig) *Client

NewClient creates a new Client that can be used to manage the Hugo Components in a given workingDir. The Client will resolve the dependencies recursively, but needs the top level imports to start out.

func (*Client) Clean

func (c *Client) Clean(pattern string) error

func (*Client) Collect

func (h *Client) Collect() (ModulesConfig, error)

func (*Client) Get

func (c *Client) Get(args ...string) error

Get runs "go get" with the supplied arguments.

func (*Client) Graph

func (c *Client) Graph(w io.Writer) error

Graph writes a module dependency graph to the given writer.

func (*Client) Init

func (c *Client) Init(path string) error

Init initializes this as a Go Module with the given path. If path is empty, Go will try to guess. If this succeeds, this project will be marked as Go Module.

func (*Client) Tidy

func (c *Client) Tidy() error

Tidy can be used to remove unused dependencies from go.mod and go.sum.

func (*Client) Vendor

func (c *Client) Vendor() error

Vendor writes all the module dependencies to a _vendor folder.

Unlike Go, we support it for any level.

We, by default, use the /_vendor folder first, if found. To disable, run with

hugo --ignoreVendorPaths=".*"

Given a module tree, Hugo will pick the first module for a given path, meaning that if the top-level module is vendored, that will be the full set of dependencies.

func (*Client) Verify

func (c *Client) Verify(clean bool) error

Verify checks that the dependencies of the current module, which are stored in a local downloaded source cache, have not been modified since being downloaded.

type ClientConfig

type ClientConfig struct {
	Fs     afero.Fs
	Logger loggers.Logger

	// If set, it will be run before we do any duplicate checks for modules
	// etc.
	HookBeforeFinalize func(m *ModulesConfig) error

	// Ignore any _vendor directory for module paths matching the given pattern.
	// This can be nil.
	IgnoreVendor glob.Glob

	// Absolute path to the project dir.
	WorkingDir string

	// Absolute path to the project's themes dir.
	ThemesDir string

	// The publish dir.
	PublishDir string

	// Eg. "production"
	Environment string

	Exec *hexec.Exec

	CacheDir     string // Module cache
	ModuleConfig Config
}

ClientConfig configures the module Client.

type Config

type Config struct {
	// File system mounts.
	Mounts []Mount

	// Module imports.
	Imports []Import

	// Meta info about this module (license information etc.).
	Params map[string]any

	// Will be validated against the running Hugo version.
	HugoVersion HugoVersion

	// Optional Glob pattern matching module paths to skip when vendoring, e.g. “github.com/**”
	NoVendor string

	// When enabled, we will pick the vendored module closest to the module
	// using it.
	// The default behavior is to pick the first.
	// Note that there can still be only one dependency of a given module path,
	// so once it is in use it cannot be redefined.
	VendorClosest bool

	// A comma separated (or a slice) list of module path to directory replacement mapping,
	// e.g. github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path.
	// This is mostly useful for temporary locally development of a module, and then it makes sense to set it as an
	// OS environment variable, e.g: env HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../..".
	// Any relative path is relate to themesDir, and absolute paths are allowed.
	Replacements []string

	// Defines the proxy server to use to download remote modules. Default is direct, which means “git clone” and similar.
	// Configures GOPROXY when running the Go command for module operations.
	Proxy string

	// Comma separated glob list matching paths that should not use the proxy configured above.
	// Configures GONOPROXY when running the Go command for module operations.
	NoProxy string

	// Comma separated glob list matching paths that should be treated as private.
	// Configures GOPRIVATE when running the Go command for module operations.
	Private string

	// Defaults to "off".
	// Set to a work file, e.g. hugo.work, to enable Go "Workspace" mode.
	// Can be relative to the working directory or absolute.
	// Requires Go 1.18+.
	// Note that this can also be set via OS env, e.g. export HUGO_MODULE_WORKSPACE=/my/hugo.work.
	Workspace string
	// contains filtered or unexported fields
}

Config holds a module config.

func DecodeConfig

func DecodeConfig(cfg config.Provider) (Config, error)

DecodeConfig creates a modules Config from a given Hugo configuration.

type HugoVersion

type HugoVersion struct {
	// The minimum Hugo version that this module works with.
	Min hugo.VersionString

	// The maximum Hugo version that this module works with.
	Max hugo.VersionString

	// Set if the extended version is needed.
	Extended bool
}

HugoVersion holds Hugo binary version requirements for a module.

func (HugoVersion) IsValid

func (v HugoVersion) IsValid() bool

IsValid reports whether this version is valid compared to the running Hugo binary.

func (HugoVersion) String

func (v HugoVersion) String() string

type Import

type Import struct {
	// Module path
	Path string

	// Ignore any config in config.toml (will still follow imports).
	IgnoreConfig bool
	// Do not follow any configured imports.
	IgnoreImports bool
	// Do not mount any folder in this import.
	NoMounts bool
	// Never vendor this import (only allowed in main project).
	NoVendor bool
	// Turn off this module.
	Disable bool
	// File mounts.
	Mounts []Mount
	// contains filtered or unexported fields
}

type Module

type Module interface {
	// Optional config read from the configFilename above.
	Cfg() config.Provider

	// The decoded module config and mounts.
	Config() Config

	// Optional configuration filenames (e.g. "/themes/mytheme/config.json").
	// This will be added to the special configuration watch list when in
	// server mode.
	ConfigFilenames() []string

	// Directory holding files for this module.
	Dir() string

	// Returns whether this is a Go Module.
	IsGoMod() bool

	// Any directory remappings.
	Mounts() []Mount

	// In the dependency tree, this is the first module that defines this module
	// as a dependency.
	Owner() Module

	// Returns the path to this module.
	// This will either be the module path, e.g. "github.com/gohugoio/myshortcodes",
	// or the path below your /theme folder, e.g. "mytheme".
	Path() string

	// Replaced by this module.
	Replace() Module

	// Returns whether Dir points below the _vendor dir.
	Vendor() bool

	// The module version.
	Version() string

	// Time version was created.
	Time() time.Time

	// Whether this module's dir is a watch candidate.
	Watch() bool
}

type Modules

type Modules []Module

type ModulesConfig

type ModulesConfig struct {
	// All active modules.
	AllModules Modules

	// Set if this is a Go modules enabled project.
	GoModulesFilename string

	// Set if a Go workspace file is configured.
	GoWorkspaceFilename string
}

func (ModulesConfig) HasConfigFile

func (m ModulesConfig) HasConfigFile() bool

type Mount

type Mount struct {
	// Relative path in source repo, e.g. "scss".
	Source string

	// Relative target path, e.g. "assets/bootstrap/scss".
	Target string

	// Any file in this mount will be associated with this language.
	Lang string

	// Include only files matching the given Glob patterns (string or slice).
	IncludeFiles any

	// Exclude all files matching the given Glob patterns (string or slice).
	ExcludeFiles any

	// Disable watching in watch mode for this mount.
	DisableWatch bool
}

func (Mount) Component

func (m Mount) Component() string

func (Mount) ComponentAndName

func (m Mount) ComponentAndName() (string, string)