Aside: Support custom icons (#2261)

Co-authored-by: HiDeoo <[email protected]>
Co-authored-by: Chris Swithinbank <[email protected]>

Author: 3 people

.changeset/brave-apples-give.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight-markdoc': minor
+---
+
+Adds support for the `icon` attribute in the `aside` tag, allowing the use of any of Starlight’s built-in icons.

.changeset/five-flowers-flash.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': minor
+---
+
+Adds support for using any of Starlight’s built-in icons in asides.

docs/src/content/docs/components/asides.mdx

@@ -132,6 +132,36 @@ A warning aside *with* a custom title.
 
 </Preview>
 
+### Use custom icons
+
+Override the default aside icons by using the [`icon`](#icon) attribute set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons).
+
+<Preview>
+
+```mdx 'icon="starlight"'
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip" icon="starlight">
+	A warning aside *with* a custom icon.
+</Aside>
+```
+
+<Fragment slot="markdoc">
+
+```markdoc 'icon="starlight"'
+{% aside type="tip" icon="starlight" %}
+A warning aside *with* a custom icon.
+{% /aside %}
+```
+
+</Fragment>
+
+<Aside slot="preview" type="tip" icon="starlight">
+	A warning aside *with* a custom icon.
+</Aside>
+
+</Preview>
+
 ## `<Aside>` Props
 
 **Implementation:** [`Aside.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/Aside.astro)
@@ -156,3 +186,9 @@ The type of aside to display:
 
 The title of the aside to display.
 If `title` is not set, the default title for the current aside `type` will be used.
+
+### `icon`
+
+**type:** [`StarlightIcon`](/reference/icons/#starlighticon-type)
+
+An aside can include an `icon` attribute set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons).

docs/src/content/docs/guides/authoring-content.mdx

@@ -151,6 +151,21 @@ Astro helps you build faster websites with [“Islands Architecture”](https://
 :::
 ```
 
+### Custom aside icons
+
+You can specify a custom icon for the aside in curly brackets following the aside type or [custom title](#custom-aside-titles), e.g. `:::tip{icon="heart"}` or `:::tip[Did you know?]{icon="heart"}` respectively.
+The icon name must be set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons).
+
+:::tip{icon="heart"}
+Astro helps you build faster websites with [“Islands Architecture”](https://docs.astro.build/en/concepts/islands/).
+:::
+
+```md
+:::tip{icon="heart"}
+Astro helps you build faster websites with [“Islands Architecture”](https://docs.astro.build/en/concepts/islands/).
+:::
+```
+
 ### More aside types
 
 Caution and danger asides are helpful for drawing a user’s attention to details that may trip them up.

packages/markdoc/index.mjs

@@ -67,6 +67,10 @@ export const StarlightMarkdocPreset = {
 		aside: {
 			render: component('@astrojs/starlight/components', 'Aside'),
 			attributes: {
+				icon: {
+					type: String,
+					required: false,
+				},
 				title: {
 					type: String,
 					required: false,

packages/markdoc/package.json

@@ -23,7 +23,7 @@
   },
   "peerDependencies": {
     "@astrojs/markdoc": ">=0.12.1",
-    "@astrojs/starlight": ">=0.34.0"
+    "@astrojs/starlight": ">=0.35.0"
   },
   "publishConfig": {
     "provenance": true

packages/starlight/__tests__/remark-rehype/asides.test.ts

@@ -1,7 +1,7 @@
 import { createMarkdownProcessor, type MarkdownProcessor } from '@astrojs/markdown-remark';
 import type { Root } from 'mdast';
 import { visit } from 'unist-util-visit';
-import { describe, expect, test } from 'vitest';
+import { describe, expect, test, vi } from 'vitest';
 import { starlightAsides, remarkDirectivesRestoration } from '../../integrations/asides';
 import { createTranslationSystemFromFs } from '../../utils/translations-fs';
 import { StarlightConfigSchema, type StarlightUserConfig } from '../../utils/user-config';
@@ -126,6 +126,80 @@ Some text
 	);
 });
 
+describe('custom icons', () => {
+	test.each(['note', 'tip', 'caution', 'danger'])('%s with custom icon', async (type) => {
+		const res = await renderMarkdown(`
+:::${type}{icon="heart"}
+Some text
+:::
+  `);
+		await expect(res.code).toMatchFileSnapshot(
+			`./snapshots/generates-aside-${type}-custom-icon.html`
+		);
+	});
+
+	test.each(['note', 'tip', 'caution', 'danger'])('%s with invalid custom icon', async (type) => {
+		// Temporarily mock console.error to avoid cluttering test output when the Astro Markdown
+		// processor logs an error before rethrowing it.
+		// https://github.com/withastro/astro/blob/98853ce7e31a8002fd7be83d7932a53cfec84d27/packages/markdown/remark/src/index.ts#L161
+		const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+		await expect(async () =>
+			renderMarkdown(
+				`
+:::${type}{icon="invalid-icon-name"}
+Some text
+:::
+		`
+			)
+		).rejects.toThrowError(
+			// We are not relying on `toThrowErrorMatchingInlineSnapshot()` and our custom snapshot
+			// serializer in this specific test as error thrown in a remark plugin includes a dynamic file
+			// path.
+			expect.objectContaining({
+				type: 'AstroUserError',
+				hint: expect.stringMatching(
+					/An aside custom icon must be set to the name of one of Starlight’s built-in icons, but received `invalid-icon-name`/
+				),
+			})
+		);
+
+		// Restore the original console.error implementation.
+		consoleError.mockRestore();
+	});
+
+	test('test custom icon with multiple paths inside the svg', async () => {
+		const res = await renderMarkdown(`
+:::note{icon="external"}
+Some text
+:::
+  `);
+		await expect(res.code).toMatchFileSnapshot(
+			`./snapshots/generates-aside-note-multiple-path-custom-icon.html`
+		);
+		const pathCount = (res.code.match(/path/g) || []).length;
+		// If we have two pairs of opening and closing tags of path,
+		// we will have 4 occurences of that word.
+		expect(pathCount).eq(4);
+	});
+});
+
+describe('custom labels with custom icons', () => {
+	test.each(['note', 'tip', 'caution', 'danger'])('%s with custom label', async (type) => {
+		const label = 'Custom Label';
+		const res = await renderMarkdown(`
+:::${type}[${label}]{icon="heart"}
+Some text
+:::
+  `);
+		expect(res.code).includes(`aria-label="${label}"`);
+		expect(res.code).includes(`</svg>${label}</p>`);
+		await expect(res.code).toMatchFileSnapshot(
+			`./snapshots/generates-aside-${type}-custom-label-and-icon.html`
+		);
+	});
+});
+
 test('ignores unknown directive variants', async () => {
 	const res = await renderMarkdown(`
 :::unknown

packages/starlight/__tests__/remark-rehype/snapshots/generates-aside-caution-custom-icon.html

@@ -0,0 +1 @@
+<aside aria-label="Caution" class="starlight-aside starlight-aside--caution"><p class="starlight-aside__title" aria-hidden="true"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon"><path d="M20.16 5A6.29 6.29 0 0 0 12 4.36a6.27 6.27 0 0 0-8.16 9.48l6.21 6.22a2.78 2.78 0 0 0 3.9 0l6.21-6.22a6.27 6.27 0 0 0 0-8.84m-1.41 7.46-6.21 6.21a.76.76 0 0 1-1.08 0l-6.21-6.24a4.29 4.29 0 0 1 0-6 4.27 4.27 0 0 1 6 0 1 1 0 0 0 1.42 0 4.27 4.27 0 0 1 6 0 4.29 4.29 0 0 1 .08 6Z"></path></svg>Caution</p><div class="starlight-aside__content"><p>Some text</p></div></aside>

packages/starlight/__tests__/remark-rehype/snapshots/generates-aside-caution-custom-label-and-icon.html

@@ -0,0 +1 @@
+<aside aria-label="Custom Label" class="starlight-aside starlight-aside--caution"><p class="starlight-aside__title" aria-hidden="true"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon"><path d="M20.16 5A6.29 6.29 0 0 0 12 4.36a6.27 6.27 0 0 0-8.16 9.48l6.21 6.22a2.78 2.78 0 0 0 3.9 0l6.21-6.22a6.27 6.27 0 0 0 0-8.84m-1.41 7.46-6.21 6.21a.76.76 0 0 1-1.08 0l-6.21-6.24a4.29 4.29 0 0 1 0-6 4.27 4.27 0 0 1 6 0 1 1 0 0 0 1.42 0 4.27 4.27 0 0 1 6 0 4.29 4.29 0 0 1 .08 6Z"></path></svg>Custom Label</p><div class="starlight-aside__content"><p>Some text</p></div></aside>

packages/starlight/__tests__/remark-rehype/snapshots/generates-aside-danger-custom-icon.html

@@ -0,0 +1 @@
+<aside aria-label="Danger" class="starlight-aside starlight-aside--danger"><p class="starlight-aside__title" aria-hidden="true"><svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" class="starlight-aside__icon"><path d="M20.16 5A6.29 6.29 0 0 0 12 4.36a6.27 6.27 0 0 0-8.16 9.48l6.21 6.22a2.78 2.78 0 0 0 3.9 0l6.21-6.22a6.27 6.27 0 0 0 0-8.84m-1.41 7.46-6.21 6.21a.76.76 0 0 1-1.08 0l-6.21-6.24a4.29 4.29 0 0 1 0-6 4.27 4.27 0 0 1 6 0 1 1 0 0 0 1.42 0 4.27 4.27 0 0 1 6 0 4.29 4.29 0 0 1 .08 6Z"></path></svg>Danger</p><div class="starlight-aside__content"><p>Some text</p></div></aside>