Skip to content
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

Jump to bottom

feat(core): siteConfig.headTags API to render extra tags in document head #8151

Merged
merged 6 commits into from Oct 12, 2022
Merged

feat(core): siteConfig.headTags API to render extra tags in document head #8151

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9d4069b
feat: headTags API for tags rendered in the head
johnnyreilly Sep 30, 2022
c8518e4
chore: update snapshots
johnnyreilly Sep 30, 2022
0ba1bd8
chore: fix test
johnnyreilly Sep 30, 2022
5a15f35
test: write tests and address slorbers feedback
johnnyreilly Oct 7, 2022
0d9b8cc
Update website/docusaurus.config.js
slorber Oct 12, 2022
f7f444f
Update website/docs/api/docusaurus.config.js.md
slorber Oct 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
9 changes: 8 additions & 1 deletion packages/docusaurus-types/src/config.d.ts
View file
Open in desktop
Expand Up @@ -8,7 +8,7 @@
import type {RuleSetRule} from 'webpack';
import type {Required as RequireKeys, DeepPartial} from 'utility-types';
import type {I18nConfig} from './i18n';
import type {PluginConfig, PresetConfig} from './plugin';
import type {PluginConfig, PresetConfig, HtmlTagObject} from './plugin';

export type ReportingSeverity = 'ignore' | 'log' | 'warn' | 'throw';

Expand Down Expand Up @@ -192,6 +192,13 @@ export type DocusaurusConfig = {
* @default ["static"]
*/
staticDirectories: string[];
/**
* An array of tags that will be inserted in the HTML `<head>`.
*
* @see https://docusaurus.io/docs/api/docusaurus-config#head
* @default []
*/
headTags: HtmlTagObject[];
/**
* An array of scripts to load. The values can be either strings or plain
* objects of attribute-value maps. The `<script>` tags will be inserted in
Expand Down
5 changes: 5 additions & 0 deletions packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap
View file
Open in desktop
Expand Up @@ -7,6 +7,7 @@ exports[`loadSiteConfig website with .cjs siteConfig 1`] = `
"baseUrlIssueBanner": true,
"clientModules": [],
"customFields": {},
"headTags": [],
"i18n": {
"defaultLocale": "en",
"localeConfigs": {},
Expand Down Expand Up @@ -44,6 +45,7 @@ exports[`loadSiteConfig website with valid async config 1`] = `
"baseUrlIssueBanner": true,
"clientModules": [],
"customFields": {},
"headTags": [],
"i18n": {
"defaultLocale": "en",
"localeConfigs": {},
Expand Down Expand Up @@ -83,6 +85,7 @@ exports[`loadSiteConfig website with valid async config creator function 1`] = `
"baseUrlIssueBanner": true,
"clientModules": [],
"customFields": {},
"headTags": [],
"i18n": {
"defaultLocale": "en",
"localeConfigs": {},
Expand Down Expand Up @@ -122,6 +125,7 @@ exports[`loadSiteConfig website with valid config creator function 1`] = `
"baseUrlIssueBanner": true,
"clientModules": [],
"customFields": {},
"headTags": [],
"i18n": {
"defaultLocale": "en",
"localeConfigs": {},
Expand Down Expand Up @@ -164,6 +168,7 @@ exports[`loadSiteConfig website with valid siteConfig 1`] = `
],
"customFields": {},
"favicon": "img/docusaurus.ico",
"headTags": [],
"i18n": {
"defaultLocale": "en",
"localeConfigs": {},
Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus/src/server/__tests__/__snapshots__/index.test.ts.snap
View file
Open in desktop
Expand Up @@ -71,6 +71,7 @@ exports[`load loads props for site with custom i18n path 1`] = `
"baseUrlIssueBanner": true,
"clientModules": [],
"customFields": {},
"headTags": [],
"i18n": {
"defaultLocale": "en",
"localeConfigs": {
Expand Down
68 changes: 68 additions & 0 deletions packages/docusaurus/src/server/__tests__/configValidation.test.ts
View file
Open in desktop
Expand Up @@ -340,6 +340,74 @@ describe('normalizeConfig', () => {
`);
});

it('accepts headTags with tagName and attributes', () => {
expect(() => {
normalizeConfig({
headTags: [
{
tagName: 'link',
attributes: {
rel: 'icon',
href: 'img/docusaurus.png',
},
},
],
});
}).not.toThrow();
});

it("throws error if headTags doesn't have tagName", () => {
expect(() => {
normalizeConfig({
headTags: [
{
attributes: {
rel: 'icon',
href: 'img/docusaurus.png',
},
},
],
});
}).toThrowErrorMatchingInlineSnapshot(`
""headTags[0].tagName" is required
"
`);
});

it("throws error if headTags doesn't have attributes", () => {
expect(() => {
normalizeConfig({
headTags: [
{
tagName: 'link',
},
],
});
}).toThrowErrorMatchingInlineSnapshot(`
""headTags[0].attributes" is required
"
`);
});

it("throws error if headTags doesn't have string attributes", () => {
expect(() => {
normalizeConfig({
headTags: [
{
tagName: 'link',
attributes: {
rel: false,
href: 'img/docusaurus.png',
},
},
],
});
}).toThrowErrorMatchingInlineSnapshot(`
""headTags[0].attributes.rel" must be a string
"
`);
});

it("throws error if css doesn't have href", () => {
expect(() => {
normalizeConfig({
Expand Down
16 changes: 16 additions & 0 deletions packages/docusaurus/src/server/configValidation.ts
View file
Open in desktop
Expand Up @@ -33,6 +33,7 @@ export const DEFAULT_CONFIG: Pick<
| 'plugins'
| 'themes'
| 'presets'
| 'headTags'
| 'stylesheets'
| 'scripts'
| 'clientModules'
Expand All @@ -51,6 +52,7 @@ export const DEFAULT_CONFIG: Pick<
plugins: [],
themes: [],
presets: [],
headTags: [],
stylesheets: [],
scripts: [],
clientModules: [],
Expand Down Expand Up @@ -214,6 +216,20 @@ export const ConfigSchema = Joi.object<DocusaurusConfig>({
})
.default(DEFAULT_CONFIG.scripts),
ssrTemplate: Joi.string(),
headTags: Joi.array()
.items(
Joi.object({
tagName: Joi.string().required(),
attributes: Joi.object()
.pattern(/[\w-]+/, Joi.string())
.required(),
}).unknown(),
)
.messages({
'array.includes':
'{#label} is invalid. A headTag must be an object with at least a "tagName" and an "attributes" property.',
})
.default(DEFAULT_CONFIG.headTags),
stylesheets: Joi.array()
.items(
Joi.string(),
Expand Down
3 changes: 2 additions & 1 deletion packages/docusaurus/src/server/plugins/synthetic.ts
View file
Open in desktop
Expand Up @@ -21,6 +21,7 @@ export function createBootstrapPlugin({
const {
stylesheets,
scripts,
headTags,
clientModules: siteConfigClientModules,
} = siteConfig;
return {
Expand Down Expand Up @@ -58,7 +59,7 @@ export function createBootstrapPlugin({
},
);
return {
headTags: [...stylesheetsTags, ...scriptsTags],
headTags: [...headTags, ...stylesheetsTags, ...scriptsTags],
};
},
};
Expand Down
24 changes: 24 additions & 0 deletions website/docs/api/docusaurus.config.js.md
View file
Open in desktop
Expand Up @@ -429,6 +429,30 @@ module.exports = {
};
```

### `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.

- Type: `{ tagName: string; attributes: Object; }[]`

Example:

```js title="docusaurus.config.js"
module.exports = {
headTags: [
{
tagName: 'link',
attributes: {
rel: 'icon',
href: '/img/docusaurus.png',
},
},
],
};
```

This would become `<link rel="icon" href="img/docusaurus.png" />` in the generated HTML.

### `scripts` {#scripts}

An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The `<script>` tags will be inserted in the HTML `<head>`. If you use a plain object, the only required attribute is `src`, and any other attributes are permitted (each one should have boolean/string values).
Expand Down