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 all 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
13 changes: 13 additions & 0 deletions packages/docusaurus/src/server/__tests__/configValidation.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -315,6 +315,19 @@ describe('headTags', () => {
`);
});

it('accepts headTags with a custom element without attributes', () => {
expect(() =>
normalizeConfig({
headTags: [
{
tagName: 'my-custom-element',
customElement: true,
},
],
}),
).not.toThrow();
});

it("throws error if headTags doesn't have string attributes", () => {
expect(() => {
normalizeConfig({
Expand Down
2 changes: 1 addition & 1 deletion packages/docusaurus/src/server/__tests__/htmlTags.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,7 @@ describe('loadHtmlTags', () => {
},
]),
).toThrowErrorMatchingInlineSnapshot(
`"Error loading {"tagName":"endiliey","attributes":{"this":"is invalid"}}, "endiliey" is not a valid HTML tag."`,
`"Error loading {"tagName":"endiliey","attributes":{"this":"is invalid"}}, "endiliey" is not a valid HTML tag. Either use a valid "tagName" or set "customElement: true"."`,
);
});

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
13 changes: 9 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 @@ -17,22 +17,27 @@ import type {
RouterType,
} from '@docusaurus/types';

// TODO this should be done at config validation time, not here
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; customElement?: boolean; }[]`

Example:

Expand Down