@astrojs/starlight 0.35.3 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @astrojs/starlight
 
+## 0.36.0
+
+### Minor Changes
+
+- [#3427](https://github.com/withastro/starlight/pull/3427) [`c3b2d0f`](https://github.com/withastro/starlight/commit/c3b2d0fc37bb9b7b6abc6c11b760a4114690ccd4) Thanks [@delucis](https://github.com/delucis)! - Fixes styling of labels that wrap across multiple lines in `<Tabs>` component
+
+  ⚠️ **Potentially breaking change:** Tab labels now have a narrower line-height and additional vertical padding. If you have custom CSS targetting the `<Tabs>` component, you may want to double check the visual appearance of your tabs when updating.
+
+  If you want to preserve the previous styling, you can add the following custom CSS to your site:
+
+  ```css
+  .tab > [role='tab'] {
+    line-height: var(--sl-line-height);
+    padding-block: 0;
+  }
+  ```
+
+- [#3380](https://github.com/withastro/starlight/pull/3380) [`3364af3`](https://github.com/withastro/starlight/commit/3364af31e535d62ee7b045e6d9cf97c7e58df981) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Makes head entry parsing stricter in Starlight config and content frontmatter.
+
+  **⚠️ Potentially breaking change:** Previously Starlight would accept a head entry for a `meta` tag defining some `content` which generates invalid HTML as `<meta>` is a void element which cannot have any child nodes. Now, it is an error to define a `meta` tag including some `content`.
+
+  If you see errors after updating, look for head entries in the Starlight configuration in the `astro.config.mjs` file or in the frontmatter of your content files that include a `content` property for a `meta` tag. To fix the error, move the `content` property to the `attrs` object with at least an additional attribute to identify the kind of metadata it represents:
+
+  ```diff
+  head: {
+    tag: 'meta',
+  - content: 'foo',
+    attrs: {
+      name: 'my-meta',
+  +   content: 'foo',
+    },
+  },
+  ```
+
+- [#3340](https://github.com/withastro/starlight/pull/3340) [`2018c31`](https://github.com/withastro/starlight/commit/2018c31b0f559d51478bfbf9f12cfba76b4e74fc) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds missing vertical spacing between Markdown content and UI Framework components using [client directives](https://docs.astro.build/en/reference/directives-reference/#client-directives).
+
+  **⚠️ Potentially breaking change:** By default, Starlight applies some vertical spacing (`--sl-content-gap-y`) between Markdown content blocks. This change introduces similar spacing between Markdown content blocks and UI Framework components using client directives which was not present before.
+
+  If you were relying on the previous behavior, you can manually override the spacing by manually specifying the top margin on the component using [custom CSS](https://starlight.astro.build/guides/css-and-tailwind/#custom-css-styles), e.g. by relying on a CSS class to target the component.
+
+  ```css
+  .my-custom-component {
+    margin-top: 0;
+  }
+  ```
+
+### Patch Changes
+
+- [#3423](https://github.com/withastro/starlight/pull/3423) [`a0d0670`](https://github.com/withastro/starlight/commit/a0d0670bce5827b90fd0102fa3517814367760e7) Thanks [@andersk](https://github.com/andersk)! - Fixes HTML validity in sidebar groups by ensuring `<summary>` is the first child of `<details>`
+
 ## 0.35.3
 
 ### Patch Changes

package/components/SidebarSublist.astro

@@ -37,7 +37,6 @@ const { sublist, nested } = Astro.props;
 					<details
 						open={flattenSidebar(entry.entries).some((i) => i.isCurrent) || !entry.collapsed}
 					>
-						<SidebarRestorePoint />
 						<summary>
 							<span class="group-label">
 								<span class="large">{entry.label}</span>
@@ -51,6 +50,7 @@ const { sublist, nested } = Astro.props;
 							</span>
 							<Icon name="right-caret" class="caret" size="1.25rem" />
 						</summary>
+						<SidebarRestorePoint />
 						<Astro.self sublist={entry.entries} nested />
 					</details>
 				)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.35.3",
+  "version": "0.36.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",

package/schema.ts

@@ -30,7 +30,7 @@ const StarlightFrontmatterSchema = (context: SchemaContext) =>
 		editUrl: z.union([z.string().url(), z.boolean()]).optional().default(true),
 
 		/** Set custom `<head>` tags just for this page. */
-		head: HeadConfigSchema(),
+		head: HeadConfigSchema({ source: 'content' }),
 
 		/** Override global table of contents configuration for this page. */
 		tableOfContents: TableOfContentsSchema().optional(),

package/schemas/head.ts

@@ -1,16 +1,47 @@
 import { z } from 'astro/zod';
+import yaml from 'js-yaml';
 
-export const HeadConfigSchema = () =>
+export const HeadConfigSchema = ({
+	source,
+}: {
+	/**
+	 * Depending on the content being validated, either a user's config or a page's frontmatter,
+	 * different error messages will be shown.
+	 */
+	source: 'config' | 'content';
+}) =>
 	z
 		.array(
-			z.object({
-				/** Name of the HTML tag to add to `<head>`, e.g. `'meta'`, `'link'`, or `'script'`. */
-				tag: z.enum(['title', 'base', 'link', 'style', 'meta', 'script', 'noscript', 'template']),
-				/** Attributes to set on the tag, e.g. `{ rel: 'stylesheet', href: '/custom.css' }`. */
-				attrs: z.record(z.union([z.string(), z.boolean(), z.undefined()])).optional(),
-				/** Content to place inside the tag (optional). */
-				content: z.string().optional(),
-			})
+			z
+				.object({
+					/** Name of the HTML tag to add to `<head>`, e.g. `'meta'`, `'link'`, or `'script'`. */
+					tag: z.enum(['title', 'base', 'link', 'style', 'meta', 'script', 'noscript', 'template']),
+					/** Attributes to set on the tag, e.g. `{ rel: 'stylesheet', href: '/custom.css' }`. */
+					attrs: z.record(z.union([z.string(), z.boolean(), z.undefined()])).optional(),
+					/** Content to place inside the tag (optional). */
+					content: z.string().optional(),
+				})
+				.superRefine((config, ctx) => {
+					if (config.tag !== 'meta' || config.content === undefined) return;
+					const { content, ...rest } = config;
+					const correctTag = {
+						...rest,
+						attrs: { ...(config.attrs ?? { name: 'identifier' }), content: config.content },
+					};
+					const code =
+						source === 'config' ? JSON.stringify(correctTag, null, 2) : yaml.dump([correctTag]);
+					ctx.addIssue({
+						code: 'custom',
+						message:
+							`The \`head\` configuration includes a \`meta\` tag with \`content\` which is invalid HTML.\n` +
+							`You should instead use a \`content\` attribute ` +
+							(Object.keys(rest.attrs ?? {}).length === 0
+								? 'with an additional attribute such as `name`, `property`, or `http-equiv` to identify the kind of metadata it represents '
+								: '') +
+							`in the \`attrs\` object:\n\n` +
+							code,
+					});
+				})
 		)
 		.default([]);
 

package/style/markdown.css

@@ -2,7 +2,15 @@
 	.sl-markdown-content
 		:not(a, strong, em, del, span, input, code, br)
 		+ :not(a, strong, em, del, span, input, code, br, :where(.not-content *)) {
-		margin-top: 1rem;
+		margin-top: var(--sl-content-gap-y);
+	}
+
+	/* Vertical spacing between Markdown content blocks and UI Framework components using client directives. */
+	.sl-markdown-content
+		:not(a, strong, em, del, span, input, code, br)
+		+ :is(astro-island, astro-slot)
+		> :not(a, strong, em, del, span, input, code, br, :where(.not-content *)):first-child {
+		margin-top: var(--sl-content-gap-y);
 	}
 
 	/* Headings after non-headings have more spacing. */

package/style/props.css

@@ -101,6 +101,7 @@
 		--sl-sidebar-pad-x: 1rem;
 		--sl-content-width: 45rem;
 		--sl-content-pad-x: 1rem;
+		--sl-content-gap-y: 1rem;
 		--sl-main-pad: 0 0 3vh 0;
 		--sl-menu-button-size: 2rem;
 		--sl-nav-gap: var(--sl-content-pad-x);

package/user-components/Tabs.astro

@@ -115,13 +115,15 @@ if (isSynced) {
 		}
 
 		.tab {
+			display: flex;
 			margin-bottom: -2px;
 		}
 		.tab > [role='tab'] {
 			display: flex;
 			align-items: center;
 			gap: 0.5rem;
-			padding: 0 1.25rem;
+			line-height: var(--sl-line-height-headings);
+			padding: 0.275rem 1.25rem;
 			text-decoration: none;
 			border-bottom: 2px solid var(--sl-color-gray-5);
 			color: var(--sl-color-gray-3);

package/utils/head.ts

@@ -7,7 +7,7 @@ import { fileWithBase } from './base';
 import { formatCanonical } from './canonical';
 import { localizedUrl } from './localizedUrl';
 
-const HeadSchema = HeadConfigSchema();
+const HeadSchema = HeadConfigSchema({ source: 'content' });
 
 /** Get the head for the current page. */
 export function getHead(

package/utils/user-config.ts

@@ -149,7 +149,7 @@ const UserConfigSchema = z.object({
 	 *  ],
 	 * })
 	 */
-	head: HeadConfigSchema(),
+	head: HeadConfigSchema({ source: 'config' }),
 
 	/**
 	 * Provide CSS files to customize the look and feel of your Starlight site.