gohugoio/hugo · error

markup must not be set, use mediaType

Error message

markup must not be set, use mediaType

What it means

When pages are created from data via the content adapter API (`pagesFromData`), `PageConfigEarly.Init` forbids setting `content.markup` (page_frontmatter.go:240-242). Content-adapter pages must declare `mediaType` instead, because the markup field is reserved for file-based content and would be ambiguous in the data API.

Solutions

1. Replace `content.markup` with `content.mediaType` (e.g. `text/markdown`) when adding pages from data.
2. Leave both unset if the default media type is acceptable.

Example fix

{{/* before */}}
{{ $.AddPage (dict "kind" "page" "path" "a/b" "content" (dict "markup" "markdown" "value" "...")) }}

{{/* after */}}
{{ $.AddPage (dict "kind" "page" "path" "a/b" "content" (dict "mediaType" "text/markdown" "value" "...")) }}

When it happens

Trigger: Calling `.AddPage` (or equivalent content-adapter hook) with a `content.markup` value set, e.g. passing `markup: markdown` when programmatically adding a page.

Common situations: Migrating file-based front matter patterns into a content adapter; following an outdated tutorial that used `markup`; assuming `markup` and `mediaType` are interchangeable.

Related errors

• cardinalityThreshold threshold must be between 0 and 100
• empty path is reserved for the home page
• failed to decode page map
• permalink attribute not recognised
• permalinks configuration not supported for kind

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/327cdfe79dfe94ba. Report an issue: GitHub.

Appendix: source

Thrown at resources/page/pagemeta/page_frontmatter.go:241

	return p.MatchRoleCoarse(siteVector) && p.MatchVersionCoarse(siteVector)
}

func DefaultPageConfig() *PageConfigLate {
	return &PageConfigLate{
		Build: DefaultBuildConfig,
	}
}

func (p *PageConfigEarly) Init(pagesFromData bool) error {
	if pagesFromData {
		p.Path = strings.TrimPrefix(p.Path, "/")

		if p.Path == "" && p.Kind != kinds.KindHome {
			return fmt.Errorf("empty path is reserved for the home page")
		}

		if p.Content.Markup != "" {
			return errors.New("markup must not be set, use mediaType")
		}
	}

	return nil
}

func (p *PageConfigLate) Init() error {
	return nil
}

func buildSitesComplementsFromSitesConfig(
	conf config.AllProvider,
	fim *hugofs.FileMeta,
	sitesConfig sitesmatrix.Sites,
) sitesmatrix.VectorStore {
	if sitesConfig.Complements.IsZero() {
		if fim != nil && fim.SitesComplements != nil {
			return fim.SitesComplements

View on GitHub (pinned to 52c9bd7908)