@astrojs/starlight 0.0.4 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/components/HeadSEO.astro +83 -42
  3. package/index.astro +0 -2
  4. package/package.json +1 -1
  5. package/schema.ts +4 -0
  6. package/schemas/head.ts +29 -0
  7. package/utils/head.ts +95 -0
  8. package/utils/user-config.ts +23 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # @astrojs/starlight
2
2
 
3
+ ## 0.0.5
4
+
5
+ ### Patch Changes
6
+
7
+ - [#42](https://github.com/withastro/starlight/pull/42) [`c6c1b67`](https://github.com/withastro/starlight/commit/c6c1b6727140a76c42c661f406000cc6e9b175de) Thanks [@delucis](https://github.com/delucis)! - Support setting custom `<head>` tags in config or frontmatter.
8
+
3
9
  ## 0.0.4
4
10
 
5
11
  ### Patch Changes
package/components/HeadSEO.astro CHANGED
@@ -1,6 +1,8 @@
1
1
  ---
2
- import type { CollectionEntry } from 'astro:content';
2
+ import type { CollectionEntry, z } from 'astro:content';
3
3
  import config from 'virtual:starlight/user-config';
4
+ import type { HeadConfigSchema } from '../schemas/head';
5
+ import { createHead } from '../utils/head';
4
6
  import { localizedUrl } from '../utils/localizedUrl';
5
7
 
6
8
  interface Props {
@@ -15,48 +17,87 @@ const canonical = Astro.site
15
17
  : undefined;
16
18
  const title = data.title || config.title;
17
19
  const description = data.description || config.description;
18
- ---
19
20
 
20
- <title>{title}</title>
21
- {description && <meta name="description" content={description} />}
22
- <link rel="canonical" href={canonical} />
23
- {
24
- canonical &&
25
- config.isMultilingual &&
26
- Object.entries(config.locales).map(
27
- ([locale, localeOpts]) =>
28
- localeOpts && (
29
- <link
30
- rel="alternate"
31
- hreflang={localeOpts.lang}
32
- href={localizedUrl(canonical, locale)}
33
- />
34
- )
35
- )
21
+ const headDefaults: z.input<ReturnType<typeof HeadConfigSchema>> = [
22
+ { tag: 'meta', attrs: { charset: 'utf-8' } },
23
+ { tag: 'meta', attrs: { name: 'viewport', content: 'width=device-width' } },
24
+ { tag: 'title', content: title },
25
+ { tag: 'link', attrs: { rel: 'canonical', href: canonical?.href } },
26
+ { tag: 'meta', attrs: { name: 'generator', content: Astro.generator } },
27
+ // Favicon
28
+ {
29
+ tag: 'link',
30
+ attrs: {
31
+ rel: 'shortcut icon',
32
+ href: import.meta.env.BASE_URL + 'favicon.svg',
33
+ type: 'image/svg+xml',
34
+ },
35
+ },
36
+ // OpenGraph Tags
37
+ { tag: 'meta', attrs: { property: 'og:title', content: title } },
38
+ { tag: 'meta', attrs: { property: 'og:type', content: 'article' } },
39
+ { tag: 'meta', attrs: { property: 'og:url', content: canonical?.href } },
40
+ { tag: 'meta', attrs: { property: 'og:locale', content: lang } },
41
+ { tag: 'meta', attrs: { property: 'og:description', content: description } },
42
+ { tag: 'meta', attrs: { property: 'og:site_name', content: config.title } },
43
+ // Twitter Tags
44
+ {
45
+ tag: 'meta',
46
+ attrs: { name: 'twitter:card', content: 'summary_large_image' },
47
+ },
48
+ { tag: 'meta', attrs: { name: 'twitter:title', content: title } },
49
+ { tag: 'meta', attrs: { name: 'twitter:description', content: description } },
50
+ ];
51
+
52
+ if (description)
53
+ headDefaults.push({
54
+ tag: 'meta',
55
+ attrs: { name: 'description', content: description },
56
+ });
57
+
58
+ // Link to language alternates.
59
+ if (canonical && config.isMultilingual) {
60
+ for (const locale in config.locales) {
61
+ const localeOpts = config.locales[locale];
62
+ if (!localeOpts) continue;
63
+ headDefaults.push({
64
+ tag: 'link',
65
+ attrs: {
66
+ rel: 'alternate',
67
+ hreflang: localeOpts.lang,
68
+ href: localizedUrl(canonical, locale).href,
69
+ },
70
+ });
71
+ }
72
+ }
73
+
74
+ // Link to sitemap, but only when `site` is set.
75
+ if (Astro.site) {
76
+ headDefaults.push({
77
+ tag: 'link',
78
+ attrs: {
79
+ rel: 'sitemap',
80
+ href: import.meta.env.BASE_URL + 'sitemap-index.xml',
81
+ },
82
+ });
36
83
  }
37
- <meta name="generator" content={Astro.generator} />
38
- <link
39
- rel="shortcut icon"
40
- href={import.meta.env.BASE_URL + 'favicon.svg'}
41
- type="image/svg+xml"
42
- />
43
- {/* Link to sitemap, but only when `site` is set. */}
44
- {Astro.site && <link rel="sitemap" href="/sitemap-index.xml" />}
45
-
46
- <!-- OpenGraph Tags -->
47
- <meta property="og:title" content={title} />
48
- <meta property="og:type" content="article" />
49
- <meta property="og:url" content={canonical} />
50
- <meta property="og:locale" content={lang} />
51
- <meta property="og:description" content={description} />
52
- <meta property="og:site_name" content={config.title} />
53
-
54
- <!-- Twitter Tags -->
55
- <meta name="twitter:card" content="summary_large_image" />
84
+
85
+ // Link to Twitter account if set in Starlight config.
86
+ if (config.social?.twitter) {
87
+ headDefaults.push({
88
+ tag: 'meta',
89
+ attrs: {
90
+ name: 'twitter:site',
91
+ content: new URL(config.social.twitter).pathname,
92
+ },
93
+ });
94
+ }
95
+
96
+ const head = createHead(headDefaults, config.head, data.head);
97
+ ---
98
+
56
99
  {
57
- config.social?.twitter && (
58
- <meta name="twitter:site" content={config.social.twitter} />
59
- )
100
+ head.map(({ tag: Tag, attrs, content }) => (
101
+ <Tag {...attrs} set:html={content} />
102
+ ))
60
103
  }
61
- <meta name="twitter:title" content={title} />
62
- <meta name="twitter:description" content={description} />
package/index.astro CHANGED
@@ -46,8 +46,6 @@ const prevNextLinks = getPrevNextLinks(sidebar);
46
46
 
47
47
  <html lang={lang} dir={dir}>
48
48
  <head>
49
- <meta charset="utf-8" />
50
- <meta name="viewport" content="width=device-width" />
51
49
  <HeadSEO data={entry.data} lang={lang} />
52
50
  </head>
53
51
  <body>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrojs/starlight",
3
- "version": "0.0.4",
3
+ "version": "0.0.5",
4
4
  "description": "Build beautiful, high-performance documentation websites with Astro",
5
5
  "keywords": [
6
6
  "docs",
package/schema.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { z } from 'astro/zod';
2
+ import { HeadConfigSchema } from './schemas/head';
2
3
 
3
4
  export function docsSchema() {
4
5
  return z.object({
@@ -19,5 +20,8 @@ export function docsSchema() {
19
20
  * Can also be set to `false` to disable showing an edit link on this page.
20
21
  */
21
22
  editUrl: z.union([z.string().url(), z.boolean()]).optional().default(true),
23
+
24
+ /** Set custom `<head>` tags just for this page. */
25
+ head: HeadConfigSchema(),
22
26
  });
23
27
  }
package/schemas/head.ts ADDED
@@ -0,0 +1,29 @@
1
+ import { z } from 'astro/zod';
2
+
3
+ export const HeadConfigSchema = () =>
4
+ z
5
+ .array(
6
+ z.object({
7
+ /** Name of the HTML tag to add to `<head>`, e.g. `'meta'`, `'link'`, or `'script'`. */
8
+ tag: z.enum([
9
+ 'title',
10
+ 'base',
11
+ 'link',
12
+ 'style',
13
+ 'meta',
14
+ 'script',
15
+ 'noscript',
16
+ 'template',
17
+ ]),
18
+ /** Attributes to set on the tag, e.g. `{ rel: 'stylesheet', href: '/custom.css' }`. */
19
+ attrs: z
20
+ .record(z.union([z.string(), z.boolean(), z.undefined()]))
21
+ .default({}),
22
+ /** Content to place inside the tag (optional). */
23
+ content: z.string().default(''),
24
+ })
25
+ )
26
+ .default([]);
27
+
28
+ export type HeadUserConfig = z.input<ReturnType<typeof HeadConfigSchema>>;
29
+ export type HeadConfig = z.output<ReturnType<typeof HeadConfigSchema>>;
package/utils/head.ts ADDED
@@ -0,0 +1,95 @@
1
+ import { HeadConfig, HeadConfigSchema, HeadUserConfig } from '../schemas/head';
2
+
3
+ const HeadSchema = HeadConfigSchema();
4
+
5
+ /** Create a fully parsed, merged, and sorted head entry array from multiple sources. */
6
+ export function createHead(defaults: HeadUserConfig, ...heads: HeadConfig[]) {
7
+ let head = HeadSchema.parse(defaults);
8
+ for (const next of heads) {
9
+ head = mergeHead(head, next);
10
+ }
11
+ return sortHead(head);
12
+ }
13
+
14
+ /**
15
+ * Test if a head config object contains a matching `<title>` or `<meta>` tag.
16
+ *
17
+ * For example, will return true if `head` already contains
18
+ * `<meta name="description" content="A">` and the passed `tag`
19
+ * is `<meta name="description" content="B">`. Tests against `name`,
20
+ * `property`, and `http-equiv` attributes for `<meta>` tags.
21
+ */
22
+ function hasTag(head: HeadConfig, entry: HeadConfig[number]): boolean {
23
+ switch (entry.tag) {
24
+ case 'title':
25
+ return head.some(({ tag }) => tag === 'title');
26
+ case 'meta':
27
+ return hasOneOf(head, entry, ['name', 'property', 'http-equiv']);
28
+ default:
29
+ return false;
30
+ }
31
+ }
32
+
33
+ /**
34
+ * Test if a head config object contains a tag of the same type
35
+ * as `entry` and a matching attribute for one of the passed `keys`.
36
+ */
37
+ function hasOneOf(
38
+ head: HeadConfig,
39
+ entry: HeadConfig[number],
40
+ keys: string[]
41
+ ): boolean {
42
+ const attr = getAttr(keys, entry);
43
+ if (!attr) return false;
44
+ const [key, val] = attr;
45
+ return head.some(({ tag, attrs }) => tag === entry.tag && attrs[key] === val);
46
+ }
47
+
48
+ /** Find the first matching key–value pair in a head entry’s attributes. */
49
+ function getAttr(
50
+ keys: string[],
51
+ entry: HeadConfig[number]
52
+ ): [key: string, value: string | boolean] | undefined {
53
+ let attr: [string, string | boolean] | undefined;
54
+ for (const key of keys) {
55
+ const val = entry.attrs[key];
56
+ if (val) {
57
+ attr = [key, val];
58
+ break;
59
+ }
60
+ }
61
+ return attr;
62
+ }
63
+
64
+ /** Merge two heads, overwriting entries in the first head that exist in the second. */
65
+ function mergeHead(oldHead: HeadConfig, newHead: HeadConfig) {
66
+ return [...oldHead.filter((tag) => !hasTag(newHead, tag)), ...newHead];
67
+ }
68
+
69
+ /** Sort head tags to place important tags first and relegate “SEO” meta tags. */
70
+ function sortHead(head: HeadConfig) {
71
+ return head.sort((a, b) => {
72
+ const aImportance = getImportance(a);
73
+ const bImportance = getImportance(b);
74
+ return aImportance > bImportance ? -1 : bImportance > aImportance ? 1 : 0;
75
+ });
76
+ }
77
+
78
+ /** Get the relative importance of a specific head tag. */
79
+ function getImportance(entry: HeadConfig[number]) {
80
+ // 1. Important meta tags.
81
+ if (
82
+ entry.tag === 'meta' &&
83
+ ('charset' in entry.attrs ||
84
+ 'http-equiv' in entry.attrs ||
85
+ entry.attrs.name === 'viewport')
86
+ ) {
87
+ return 100;
88
+ }
89
+ // 2. Page title
90
+ if (entry.tag === 'title') return 90;
91
+ // 3. Anything that isn’t an SEO meta tag.
92
+ if (entry.tag !== 'meta') return 80;
93
+ // 4. SEO meta tags.
94
+ return 0;
95
+ }
package/utils/user-config.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { z } from 'astro/zod';
2
2
  import { parse as bcpParse, stringify as bcpStringify } from 'bcp-47';
3
+ import { HeadConfigSchema } from '../schemas/head';
3
4
 
4
5
  const LocaleSchema = z.object({
5
6
  /** The label for this language to show in UI, e.g. `"English"`, `"العربية"`, or `"简体中文"`. */
@@ -193,6 +194,28 @@ const UserConfigSchema = z.object({
193
194
  /** Configure your site’s sidebar navigation items. */
194
195
  sidebar: SidebarGroupSchema.array().optional(),
195
196
 
197
+ /**
198
+ * Add extra tags to your site’s `<head>`.
199
+ *
200
+ * Can also be set for a single page in a page’s frontmatter.
201
+ *
202
+ * @example
203
+ * // Add Fathom analytics to your site
204
+ * starlight({
205
+ * head: [
206
+ * {
207
+ * tag: 'script',
208
+ * attrs: {
209
+ * src: 'https://cdn.usefathom.com/script.js',
210
+ * 'data-site': 'MY-FATHOM-ID',
211
+ * defer: true,
212
+ * },
213
+ * },
214
+ * ],
215
+ * })
216
+ */
217
+ head: HeadConfigSchema(),
218
+
196
219
  /**
197
220
  * Provide CSS files to customize the look and feel of your Starlight site.
198
221
  *