Skip to content

feat(core): support custom html elements in head tags #11571

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
slorber merged 7 commits into from
Nov 27, 2025
Merged

feat(core): support custom html elements in head tags #11571

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6dd85b8
feat(core): support custom html elements in head tags
lebalz Nov 25, 2025
2ca4a65
update docs
lebalz Nov 25, 2025
8d60681
add unit test + comment
slorber Nov 27, 2025
fb00132
simplify docs
slorber Nov 27, 2025
099bf59
empty
slorber Nov 27, 2025
78d8eab
trigger ci
slorber Nov 27, 2025
4c60a50
update test snapshot
slorber Nov 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions packages/docusaurus-types/src/plugin.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,8 @@ export type HtmlTagObject = {
tagName: string;
/** The inner HTML */
innerHTML?: string;
/** Allow custom html elements, e.g. `<custom-element>` */
customElement?: boolean;
};

export type HtmlTags = string | HtmlTagObject | (string | HtmlTagObject)[];
Expand Down
11 changes: 8 additions & 3 deletions packages/docusaurus/src/server/configValidation.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -437,9 +437,14 @@ export const ConfigSchema = Joi.object<DocusaurusConfig>({
.items(
Joi.object({
tagName: Joi.string().required(),
attributes: Joi.object()
.pattern(/[\w-]+/, Joi.string())
.required(),
attributes: Joi.object().when('customElement', {
is: Joi.valid(true),
then: Joi.optional(),
otherwise: Joi.object()
.pattern(/[\w-]+/, Joi.string())
.required(),
}),
customElement: Joi.bool().default(false),
}).unknown(),
)
.messages({
Expand Down
12 changes: 8 additions & 4 deletions packages/docusaurus/src/server/htmlTags.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,18 +21,22 @@ function assertIsHtmlTagObject(val: unknown): asserts val is HtmlTagObject {
if (typeof val !== 'object' || !val) {
throw new Error(`"${val}" is not a valid HTML tag object.`);
}
if (typeof (val as HtmlTagObject).tagName !== 'string') {
const htmlTag = val as HtmlTagObject;
if (typeof htmlTag.tagName !== 'string') {
throw new Error(
`${JSON.stringify(
val,
)} is not a valid HTML tag object. "tagName" must be defined as a string.`,
);
}
if (!(htmlTags as string[]).includes((val as HtmlTagObject).tagName)) {
if (
!htmlTag.customElement &&
!(htmlTags as string[]).includes(htmlTag.tagName)
) {
throw new Error(
`Error loading ${JSON.stringify(val)}, "${
(val as HtmlTagObject).tagName
}" is not a valid HTML tag.`,
htmlTag.tagName
}" is not a valid HTML tag. Either use a valid "tagName" or set "customElement: true".`,
);
}
}
Expand Down
4 changes: 2 additions & 2 deletions website/docs/api/docusaurus.config.js.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -767,9 +767,9 @@ export default {

### `headTags` {#headTags}

An array of tags that will be inserted in the HTML `<head>`. The values must be objects that contain two properties; `tagName` and `attributes`. `tagName` must be a string that determines the tag being created; eg `"link"`. `attributes` must be an attribute-value map.
An array of tags that will be inserted in the HTML `<head>`. The values must be objects that contain two properties; `tagName` and `attributes`. `tagName` must be a string that determines the tag being created; eg `"link"`. `attributes` must be an attribute-value map. When custom html elements are needed, set `customElement: true`.

- Type: `{ tagName: string; attributes: Object; }[]`
- Type: `({ tagName: string; attributes: Object; } | { tagName: string; attributes?: Object; customElement: true; })[]`
Copy link
Copy Markdown
Collaborator

@slorber slorber Nov 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to avoid the union type in docs. Although more accurate, it could make the docs harder to read for the usual case where devs are not using custom elements

Although we can be flexible, I'm not sure what could be the value of adding a custom element in head if it doesn't have any attribute. It would only be a "marker" somehow, but it's not really your use-case. I think it's fine if we keep documenting it as if the attributes were required (the object can be empty anyway)


Example:

Expand Down
⚡