mui/material-ui · error · Error

docs-infra: The title "${title}" is too long (${title.length

Error message

docs-infra: The title "${title}" is too long (${title.length} characters).\nIt needs to have fewer than 70 characters—ideally less than 60. For more details, see:\nhttps://developers.google.com/search/docs/advanced/appearance/title-link\n

What it means

During docs build, prepareMarkdown reads the page title (from the `title:` frontmatter header or the first H1) and enforces Google's SEO title-link guidance: titles must be 70 characters or fewer, ideally under 60. A longer title fails the build so the published page does not get truncated in search results.

Source

Thrown at packages-internal/markdown/prepareMarkdown.mjs:104

  translations
    // Process the English markdown before the other locales.
    // English ToC anchor links are used in all languages
    .sort((a) => (a.userLanguage === 'en' ? -1 : 1))
    .forEach((translation) => {
      const { filename, markdown, userLanguage } = translation;
      const headers = getHeaders(markdown);
      const location = headers.filename || `/${fileRelativeContext}/${filename}`;
      const markdownH1 = getTitle(markdown);
      const title = headers.title || markdownH1;
      const description = headers.description || getDescription(markdown);

      if (title == null || title === '') {
        throw new Error(`docs-infra: Missing title in the page: ${location}\n`);
      }

      if (title.length > 70) {
        throw new Error(
          [
            `docs-infra: The title "${title}" is too long (${title.length} characters).`,
            'It needs to have fewer than 70 characters—ideally less than 60. For more details, see:',
            'https://developers.google.com/search/docs/advanced/appearance/title-link',
            '',
          ].join('\n'),
        );
      }

      if (description == null || description === '') {
        throw new Error(`docs-infra: Missing description in the page: ${location}\n`);
      }

      if (description.length > 160) {
        throw new Error(
          [
            `docs-infra: The description "${description}" is too long (${description.length} characters).`,
            'It needs to have fewer than 170 characters—ideally less than 160. For more details, see:',

View on GitHub (pinned to bdc96df2cb)

Solutions

Edit the page's `title:` frontmatter (or the H1) to 60 characters or fewer.
Move detail into the `description:` header instead of the title.
Re-run `pnpm docs:build` to confirm the fix.

Example fix

---
title: This is a very long docs page title that goes well beyond the seventy character limit imposed by the build
---
// after
---
title: Short page title
description: The longer explanation moves here.
---

Defensive patterns

Strategy: validation

Validate before calling

function validateTitle(title) {
  if (typeof title !== 'string' || title.length === 0) throw new Error('Missing title');
  if (title.length > 70) throw new Error(`Title too long: ${title.length} chars`);
  return title;
}
// run validateTitle on the markdown frontmatter before committing docs

Prevention

Add a pre-commit/docs lint rule that checks title length <= 70 (ideally <= 60).
Keep titles short by moving detail into the description header.
Run `pnpm docs:build` locally before pushing docs changes.

When it happens

Trigger: Authoring a markdown docs/blog page whose `title:` header (or first # heading) exceeds 70 characters; the build runs prepareMarkdown and throws before generating the page.

Common situations: Writing a new docs page or blog post with an overly descriptive title; copy-pasting a section heading as the title.

Related errors

AI-assisted analysis of mui/material-ui@bdc96df2cb (2026-08-12). Data as JSON: /api/errors/c37af7836d6abcc6. Report an issue: GitHub.