Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

The headTags configuration rejects boolean HTML attribute values during validation, despite three pieces of evidence showing this is unintentional:

1. TypeScript types allow booleans — @docusaurus/types defines attributes?: Partial<{[key: string]: string | boolean}>
2. Renderer handles booleans — packages/docusaurus/src/server/htmlTags.ts:68-70 explicitly handles boolean attributes, rendering true as the attribute name alone and false as omitted
3. Sibling scripts config accepts booleans — configValidation.ts uses .unknown() which allows boolean values, and the docs say "you might want to add async: true/defer: true"

Reproducible demo

https://new.docusaurus.io — create a new project and add the headTags config shown below.

Steps to reproduce

1. Create a fresh Docusaurus project:

npx create-docusaurus@3.10.1 my-repro classic --javascript
cd my-repro

1. Add this to docusaurus.config.js:

const config = {
  headTags: [
    {
      tagName: 'script',
      attributes: {
        src: '/analytics.js',
        async: true,
      },
    },
  ],
  // ... rest of config
};

1. Run:

npm run build

Expected behavior

The configuration should accept valid HTML boolean attributes such as async, defer, and disabled, consistent with the published TypeScript types and rendering behavior.

Actual behavior

Build fails with:

[ERROR] Error: "headTags[0].attributes.async" must be a string

The validation schema uses Joi.string() which restricts all attribute values to strings, contradicting the TypeScript type definition and the renderer's boolean handling.

Your environment

• Docusaurus: 3.10.1 (npm release)
• Node.js: v24.14.0
• Package manager: npm
• OS: Windows 11

Self-service

• I'd be willing to fix this bug myself.