elastic / elastic/docs-builder

Add meta_title frontmatter field to docs-builder

Open
#3,938 3 comments 0 reactions 1 assignee Claimed by @theletterf View on GitHub
enhancement
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

## Summary

The new [title guidance for Elastic Docs](https://github.com/elastic/docs-content-internal/blob/main/docs/style-guide/titles.md) defines a `meta_title` frontmatter field that does not yet exist in docs-builder.

## What it's for

`meta_title` controls the HTML `` tag independently of the H1. It's needed for two cases:

- **Pattern B pages** — where the H1 intentionally omits the product name (e.g. `Query DSL`), so the page title needs a qualifier: `Query DSL - Elasticsearch | Elastic Docs`
- **API operation pages** — always need `{H1} - {Product} API | Elastic Docs` as the page title regardless of the H1

Without this field, Pattern B pages and all API operation pages fall back to `{H1} | Elastic Docs`, losing the product qualifier in search results.

## Title resolution logic

The build system should determine the page title (`<title>` tag) using the following order of precedence:

1. If `meta_title` is set in frontmatter → use `{meta_title} | Elastic Docs`
2. Otherwise → fall back to `{H1} | Elastic Docs`

Authors write the title portion only (without the suffix). The build system appends `| Elastic Docs`.

## Suffix change

As part of this work, the per-repo suffix used today (e.g. `| Elasticsearch Reference`, `| Beats`, `| Logstash`) should be replaced with a single unified suffix: `| Elastic Docs`.

This applies to all repos. The suffix is appended automatically by the build system — authors never type it manually.

## Example frontmatter

```yaml
---
navigation_title: Query DSL
meta_title: Query DSL - Elasticsearch
---
```

Renders as: `<title>Query DSL - Elasticsearch | Elastic Docs`

## Reference

Title guidance doc: https://github.com/elastic/docs-content-internal/blob/main/docs/style-guide/titles.md

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.