gohugoio/hugo · error
markup must not be set, use mediaType
Error message
markup must not be set, use mediaType
What it means
Pages created from data via content adapters must not set the legacy `markup` field; Hugo requires the content format to be expressed as a media type instead (content.mediaType). PageConfigEarly.Init enforces this so the data-driven page API stays on the newer, unambiguous mediaType mechanism rather than the file-extension-era markup identifiers.
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.SitesComplementsView on GitHub ↗ (pinned to 8a468df065)
Solutions
- Replace content.markup with content.mediaType in the AddPage dict, e.g. "mediaType" "text/markdown".
- For HTML content use "mediaType" "text/html"; consult the media types config for other formats.
Example fix
{{/* before */}}
{{ .AddPage (dict "path" "p1" "content" (dict "markup" "md" "value" $body)) }}
{{/* after */}}
{{ .AddPage (dict "path" "p1" "content" (dict "mediaType" "text/markdown" "value" $body)) }} Defensive patterns
Strategy: validation
Validate before calling
# in content adapter / front matter with explicit content: content: mediaType: "text/markdown" # use mediaType, NOT markup
Prevention
- When supplying `content` with a media type (content adapters), set `mediaType`, not `markup`
- Reserve `markup` for regular page front matter without an explicit content block
- Follow the current content-adapter docs; the two keys are mutually exclusive here
When it happens
Trigger: A content adapter calling .AddPage with a dict containing content.markup, e.g. (dict "content" (dict "markup" "md" "value" $body)) — only for pagesFromData; regular file front matter may still use markup.
Common situations: Porting examples or front matter conventions from file-based content (where `markup: md` is valid) into _content.gotmpl adapters; older blog posts/tutorials predating the mediaType requirement.
Related errors
- failed to resolve media type for suffix %q
- unsupported data file extension %q
- failed to detect target data serialization format
- MIME %q not supported
- unsupported transpiler %q; valid values are %q or %q
AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31).
Data as JSON: /data/errors/327cdfe79dfe94ba.json.
Report an issue: GitHub ↗.