Add `<Aside>` component (#1499)

* Temporarily copy/paste `urlToSlug()` from #1175

* Add `<Aside>` component

* Document `<Aside>` component

* Add changeset

* Nicer formatting of multiline aside

4 files changed, 101 insertions, 0 deletions

diff --git a/.changeset/tasty-pans-camp.md b/.changeset/tasty-pans-camp.md
new file mode 100644
index 00000000..811ee0e2
--- /dev/null
+++ b/.changeset/tasty-pans-camp.md
@@ -0,0 +1,7 @@
+---
+'@astrojs/starlight': minor
+---
+
+Adds a new `<Aside>` component
+
+The new component is in addition to the existing custom Markdown syntax.
diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx
index 395b9baf..e1737838 100644
--- a/docs/src/content/docs/guides/components.mdx
+++ b/docs/src/content/docs/guides/components.mdx
@@ -169,6 +169,61 @@ import { LinkCard } from '@astrojs/starlight/components';
 	<LinkCard title="Components" href="/guides/components/" />
 </CardGrid>
 
+### Asides
+
+Asides (also known as “admonitions” or “callouts”) are useful for displaying secondary information alongside a page’s main content.
+
+An `<Aside>` can have an optional `type` of `note` (the default), `tip`, `caution` or `danger`. Setting a `title` attribute overrides the default aside title.
+
+````mdx
+# src/content/docs/example.mdx
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside>A default aside without a custom title.</Aside>
+
+<Aside type="caution" title="Watch out!">
+	A warning aside *with* a custom title.
+</Aside>
+
+<Aside type="tip">
+
+Other content is also supported in asides.
+
+```js
+// A code snippet, for example.
+```
+
+</Aside>
+
+<Aside type="danger">Do not give your password to anyone.</Aside>
+````
+
+The above code generates the following on the page:
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside>A default aside without a custom title.</Aside>
+
+<Aside type="caution" title="Watch out!">
+	A warning aside *with* a custom title.
+</Aside>
+
+<Aside type="tip">
+
+Other content is also supported in asides.
+
+```js
+// A code snippet, for example.
+```
+
+</Aside>
+
+<Aside type="danger">Do not give your password to anyone.</Aside>
+
+Starlight also provides a custom syntax for rendering asides in Markdown and MDX as an alternative to the `<Aside>` component.
+See the [“Authoring Content in Markdown”](/guides/authoring-content/#asides) guide for details of the custom syntax.
+
 ### Icon
 
 import { Icon } from '@astrojs/starlight/components';
diff --git a/packages/starlight/components.ts b/packages/starlight/components.ts
index 15fc9de3..73086297 100644
--- a/packages/starlight/components.ts
+++ b/packages/starlight/components.ts
@@ -1,3 +1,4 @@
+export { default as Aside } from './user-components/Aside.astro';
 export { default as Card } from './user-components/Card.astro';
 export { default as CardGrid } from './user-components/CardGrid.astro';
 export { default as Icon } from './user-components/Icon.astro';
diff --git a/packages/starlight/user-components/Aside.astro b/packages/starlight/user-components/Aside.astro
new file mode 100644
index 00000000..471f2fa0
--- /dev/null
+++ b/packages/starlight/user-components/Aside.astro
@@ -0,0 +1,38 @@
+---
+import { AstroError } from 'astro/errors';
+import { slugToLocaleData, urlToSlug } from '../utils/slugs';
+import { useTranslations } from '../utils/translations';
+import Icon from './Icon.astro';
+
+const asideVariants = ['note', 'tip', 'caution', 'danger'] as const;
+const icons = { note: 'information', tip: 'rocket', caution: 'warning', danger: 'error' } as const;
+
+interface Props {
+	type?: (typeof asideVariants)[number];
+	title?: string;
+}
+
+let { type = 'note', title } = Astro.props;
+
+if (!asideVariants.includes(type)) {
+	throw new AstroError(
+		'Invalid `type` prop passed to the `<Aside>` component.\n',
+		`Received: ${JSON.stringify(type)}\n` +
+			`Expected one of ${asideVariants.map((i) => JSON.stringify(i)).join(', ')}`
+	);
+}
+
+if (!title) {
+	const { locale } = slugToLocaleData(urlToSlug(Astro.url));
+	title = useTranslations(locale)(`aside.${type}`);
+}
+---
+
+<aside aria-label={title} class={`starlight-aside starlight-aside--${type}`}>
+	<p class="starlight-aside__title" aria-hidden="true">
+		<Icon name={icons[type]} class="starlight-aside__icon" />{title}
+	</p>
+	<section class="starlight-aside__content">
+		<slot />
+	</section>
+</aside>