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

• Variables
• func ApplyProjectConfigDefaults(cfg config.Provider, mod Module) error
• func IsNotExist(err error) bool
• 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
  • func CreateProjectModule(cfg config.Provider) (Module, error)
• type Modules
• type ModulesConfig
• type Mount
  • func (m Mount) Component() string
  • func (m Mount) ComponentAndName() (string, string)

Variables

var DefaultModuleConfig = Config{

	Proxy: "direct",

	NoProxy: "none",

	Private: "*.*",

	Replacements: nil,
}

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

Functions

func ApplyProjectConfigDefaults

func ApplyProjectConfigDefaults(cfg config.Provider, mod Module) error

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

func IsNotExist

func IsNotExist(err error) bool

IsNotExist returns whether an error means that a module could not be found.

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 dependenchy 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

	// Eg. "production"
	Environment string

	Exec *hexec.Exec

	CacheDir     string // Module cache
	ModuleConfig Config
}

ClientConfig configures the module Client.

type Config

type Config struct {
	Mounts  []Mount
	Imports []Import

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

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

	// A 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 behaviour 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

	Replacements []string

	// Configures GOPROXY.
	Proxy string
	// Configures GONOPROXY.
	NoProxy string
	// Configures GOPRIVATE.
	Private string

	// Set the workspace file to use, e.g. hugo.work.
	// Enables Go "Workspace" mode.
	// Requires Go 1.18+
	// See https://tip.golang.org/doc/go1.18
	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 {
	Path string // Module path

	IgnoreConfig  bool // Ignore any config in config.toml (will still follow imports).
	IgnoreImports bool // Do not follow any configured imports.
	NoMounts      bool // Do not mount any folder in this import.
	NoVendor      bool // Never vendor this import (only allowed in main project).
	Disable       bool // Turn off this module.
	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

	// This module is disabled.
	Disabled() bool

	// 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
}

func CreateProjectModule

func CreateProjectModule(cfg config.Provider) (Module, error)

CreateProjectModule creates modules from the given config. This is used in tests only.

type Modules

type Modules []Module

type ModulesConfig

type ModulesConfig struct {
	// All modules, including any disabled.
	AllModules Modules

	// All active modules.
	ActiveModules Modules

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

type Mount

type Mount struct {
	Source string // relative path in source repo, e.g. "scss"
	Target string // relative target path, e.g. "assets/bootstrap/scss"

	Lang string // any language code associated with this mount.

	// 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
}

func (Mount) Component

func (m Mount) Component() string

func (Mount) ComponentAndName

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