yq --front-matter: Edit Markdown Front Matter
yq --front-matter targets the YAML block delimited by --- at the top of a Markdown file, leaving the prose untouched.
Static-site and docs pipelines store metadata in front matter. yq can read or rewrite that block without disturbing the Markdown that follows it.
What it does
yq --front-matter=process applies the expression to the leading YAML front matter block and writes the file back with the Markdown body preserved. --front-matter=extract pulls just the front matter out as YAML. The body after the closing --- is treated as opaque text.
Common usage
# update a field in the front matter, keep the body
yq --front-matter=process -i '.draft = false' post.md
# extract the front matter as YAML
yq --front-matter=extract '.' post.md
# read one front-matter field
yq --front-matter=extract '.title' post.mdFront-matter modes
| Flag | What it does |
|---|---|
| --front-matter=process | Edit the front matter, keep the body |
| --front-matter=extract | Output only the front matter as YAML |
| -i | Write the file back in place (with process) |
| .field = value | Standard yq assignment inside the block |
In CI
A docs pipeline can stamp a build date into every post: yq --front-matter=process -i '.updated = strenv(DATE)' content/*.md. process keeps the prose intact, so only the metadata changes.
Common errors in CI
Running plain yq -i on a Markdown file (without --front-matter) treats the whole file as YAML and either errors on the prose or destroys the body; always use --front-matter=process for Markdown. A file missing the leading --- delimiters has no front matter for yq to find, so the expression sees null. Python yq has no front-matter mode at all.