@astrojs/starlight 0.7.3 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @astrojs/starlight
 
+## 0.8.1
+
+### Patch Changes
+
+- [#612](https://github.com/withastro/starlight/pull/612) [`1b367e3`](https://github.com/withastro/starlight/commit/1b367e3f65e3736b5f91c9853a487f7f5d174a6f) Thanks [@KubaJastrz](https://github.com/KubaJastrz)! - Avoid applying hovered `<select>` text color to its `<options>`
+
+## 0.8.0
+
+### Minor Changes
+
+- [#529](https://github.com/withastro/starlight/pull/529) [`c2d0e7f`](https://github.com/withastro/starlight/commit/c2d0e7f2699e60a48a3a9074eee6439dee8624a1) Thanks [@delucis](https://github.com/delucis)! - For improved compatibility with Tailwind, some Starlight built-in class names are now prefixed with `"sl-"`.
+
+  While not likely, if you were relying on one of these internal class names in your own components or custom CSS, you will need to update to use the prefixed version.
+
+  - **Before:** `flex`, `md:flex`, `lg:flex`, `block`, `md:block`, `lg:block`, `hidden`, `md:hidden`, `lg:hidden`.
+  - **After:** `sl-flex`, `md:sl-flex`, `lg:sl-flex`, `sl-block`, `md:sl-block`, `lg:sl-block`, `sl-hidden`, `md:sl-hidden`, `lg:sl-hidden`.
+
+- [#593](https://github.com/withastro/starlight/pull/593) [`5b8af95`](https://github.com/withastro/starlight/commit/5b8af95049781954eabc3895027218b3de8ff054) Thanks [@delucis](https://github.com/delucis)! - Add announcement banner feature
+
+- [#516](https://github.com/withastro/starlight/pull/516) [`70a32a1`](https://github.com/withastro/starlight/commit/70a32a1736c776febb34cf0ca3014f375ff9fec8) Thanks [@kevinzunigacuellar](https://github.com/kevinzunigacuellar)! - Support adding badges to sidebar links from config file and frontmatter
+
+### Patch Changes
+
+- [#569](https://github.com/withastro/starlight/pull/569) [`a7691f8`](https://github.com/withastro/starlight/commit/a7691f82fdabb1c4e6b14bcfa8289aaceb929997) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Use locale when sorting autogenerated sidebar entries
+
+- [#559](https://github.com/withastro/starlight/pull/559) [`5726353`](https://github.com/withastro/starlight/commit/5726353f1a4815df9ab5a7acd7aea6af53383adc) Thanks [@delucis](https://github.com/delucis)! - Add Stack Overflow icon
+
 ## 0.7.3
 
 ### Patch Changes

package/README.md

@@ -1,15 +1,17 @@
 # <img src="https://github.com/withastro/starlight/assets/357379/494fcd83-42aa-4891-87e0-87402fa0b6f3" alt="" align="left" width="40" height="40"> Starlight
 
-> **Warning**
-> This tool is an early release and very much still work in progress!  
-> [Open an issue on GitHub](https://github.com/withastro/starlight/issues/new/choose) if you find something that’s not working.
-
 Starlight is a documentation website framework for [Astro][astro].
 
 ## Documentation
 
 [Read the Starlight docs][docs] (they’re built with Starlight!)
 
+## Support
+
+Get help in the [Astro Discord][discord]. Post questions in our `#support` forum with the “starlight” tag, or visit our dedicated `#starlight` channel to discuss current development and more!
+
+You can also submit bug reports and feature requests as [GitHub issues][issues].
+
 ## Contributing
 
 Join us as a Starlight contributor! These links will help you get started:
@@ -17,6 +19,7 @@ Join us as a Starlight contributor! These links will help you get started:
 - [Contributor Manual][contributing]
 - [Code of Conduct][coc]
 - [Community Guide][community]
+- [Join the `#starlight` channel on Discord][discord]
 
 ## License
 
@@ -30,3 +33,5 @@ Copyright (c) 2023–present [Starlight contributors][contributors]
 [coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md
 [community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md
 [contributors]: https://github.com/withastro/starlight/graphs/contributors
+[discord]: https://astro.build/chat/
+[issues]: https://github.com/withastro/starlight/issues

package/components/Badge.astro

@@ -0,0 +1,86 @@
+---
+import type { Badge } from '../schemas/badge';
+
+interface Props {
+	variant?: Badge['variant'] | 'outline';
+	text?: string;
+}
+const { variant = 'default', text } = Astro.props;
+---
+
+<span class:list={['sl-badge', variant]} set:html={text} />
+
+<style>
+	.sl-badge {
+		display: inline-block;
+		border: 1px solid var(--sl-color-border-badge);
+		border-radius: 0.25rem;
+		font-family: var(--sl-font-system-mono);
+		font-size: var(--sl-text-xs);
+		font-weight: 400;
+		padding: 0.125rem 0.375rem;
+		line-height: 1;
+		color: #fff;
+		background-color: var(--sl-color-bg-badge);
+	}
+
+	.outline {
+		--sl-color-bg-badge: transparent;
+		--sl-color-border-badge: currentColor;
+		color: inherit;
+	}
+
+	.default {
+		--sl-color-bg-badge: var(--sl-color-accent-low);
+		--sl-color-border-badge: var(--sl-color-accent);
+	}
+
+	.note {
+		--sl-color-bg-badge: var(--sl-color-blue-low);
+		--sl-color-border-badge: var(--sl-color-blue);
+	}
+
+	.danger {
+		--sl-color-bg-badge: var(--sl-color-red-low);
+		--sl-color-border-badge: var(--sl-color-red);
+	}
+
+	.success {
+		--sl-color-bg-badge: var(--sl-color-green-low);
+		--sl-color-border-badge: var(--sl-color-green);
+	}
+
+	.caution {
+		--sl-color-bg-badge: var(--sl-color-orange-low);
+		--sl-color-border-badge: var(--sl-color-orange);
+	}
+
+	.tip {
+		--sl-color-bg-badge: var(--sl-color-purple-low);
+		--sl-color-border-badge: var(--sl-color-purple);
+	}
+
+	:global([data-theme='light']) .default {
+		--sl-color-bg-badge: var(--sl-color-accent-high);
+	}
+
+	:global([data-theme='light']) .note {
+		--sl-color-bg-badge: var(--sl-color-blue-high);
+	}
+
+	:global([data-theme='light']) .danger {
+		--sl-color-bg-badge: var(--sl-color-red-high);
+	}
+
+	:global([data-theme='light']) .success {
+		--sl-color-bg-badge: var(--sl-color-green-high);
+	}
+
+	:global([data-theme='light']) .caution {
+		--sl-color-bg-badge: var(--sl-color-orange-high);
+	}
+
+	:global([data-theme='light']) .tip {
+		--sl-color-bg-badge: var(--sl-color-purple-high);
+	}
+</style>

package/components/Banner.astro

@@ -0,0 +1,23 @@
+---
+interface Props {
+	content: string;
+}
+---
+
+<div class="sl-banner" role="banner" set:html={Astro.props.content} />
+
+<style>
+	.sl-banner {
+		--__sl-banner-text: var(--sl-color-banner-text, var(--sl-color-text-invert));
+		padding: var(--sl-nav-pad-y) var(--sl-nav-pad-x);
+		background-color: var(--sl-color-banner-bg, var(--sl-color-bg-accent));
+		color: var(--__sl-banner-text);
+		line-height: var(--sl-line-height-headings);
+		text-align: center;
+		text-wrap: balance;
+		box-shadow: var(--sl-shadow-sm);
+	}
+	.sl-banner :global(a) {
+		color: var(--__sl-banner-text);
+	}
+</style>

package/components/CallToAction.astro

@@ -11,7 +11,7 @@ interface Props {
 const { link, variant, icon } = Astro.props;
 ---
 
-<a class:list={['flex action', variant]} href={link}>
+<a class:list={['sl-flex action', variant]} href={link}>
 	<slot />
 	{icon?.type === 'icon' && <Icon name={icon.name} size="1.5rem" />}
 	{icon?.type === 'raw' && <Fragment set:html={icon.html} />}

package/components/ContentPanel.astro

@@ -1,5 +1,5 @@
 <div class="content-panel">
-	<div class="container"><slot /></div>
+	<div class="sl-container"><slot /></div>
 </div>
 
 <style>
@@ -9,16 +9,16 @@
 	.content-panel + .content-panel {
 		border-top: 1px solid var(--sl-color-hairline);
 	}
-	.container {
+	.sl-container {
 		max-width: var(--sl-content-width);
 	}
 
-	.container > :global(* + *) {
+	.sl-container > :global(* + *) {
 		margin-top: 1.5rem;
 	}
 
 	@media (min-width: 72rem) {
-		.container {
+		.sl-container {
 			margin-inline: var(--sl-content-margin-inline, auto);
 		}
 	}

package/components/EditLink.astro

@@ -26,7 +26,7 @@ const url =
 
 {
 	editUrl !== false && url && (
-		<a href={url} class="flex">
+		<a href={url} class="sl-flex">
 			<Icon name="pencil" size="1.2em" />
 			{t('page.editLink')}
 		</a>

package/components/FallbackContentNotice.astro

@@ -9,7 +9,7 @@ interface Props {
 const t = useTranslations(Astro.props.locale);
 ---
 
-<p class="flex">
+<p class="sl-flex">
 	<Icon name={'warning'} size="1.5em" color="var(--sl-color-orange-high)" /><span
 		>{t('i18n.untranslatedContent')}</span
 	>

package/components/Footer.astro

@@ -21,7 +21,7 @@ const prevNextLinks = getPrevNextLinks(sidebar, config.pagination, {
 ---
 
 <footer>
-	<div class="meta flex">
+	<div class="meta sl-flex">
 		{config.editLink.baseUrl && <EditLink data={entry.data} id={entry.id} {locale} />}
 		{
 			(entry.data.lastUpdated ?? config.lastUpdated) && (

package/components/Header.astro

@@ -12,10 +12,10 @@ interface Props {
 const { locale } = Astro.props;
 ---
 
-<div class="header flex">
+<div class="header sl-flex">
 	<SiteTitle {locale} />
 	<Search {locale} />
-	<div class="hidden md:flex right-group">
+	<div class="sl-hidden md:sl-flex right-group">
 		<SocialIcons />
 		<ThemeSelect {locale} />
 		<LanguageSelect {locale} />

package/components/Hero.astro

@@ -28,17 +28,17 @@ const imageAttrs = {
 				<Image src={image.file} {...imageAttrs} />
 			)
 		) : (
-			image?.html && <div class="hero-html flex" set:html={image.html} />
+			image?.html && <div class="hero-html sl-flex" set:html={image.html} />
 		)
 	}
-	<div class="flex stack">
-		<div class="flex copy">
+	<div class="sl-flex stack">
+		<div class="sl-flex copy">
 			<h1 id="_top" data-page-title set:html={title} />
 			{tagline && <div class="tagline" set:html={tagline} />}
 		</div>
 		{
 			actions.length > 0 && (
-				<div class="flex actions">
+				<div class="sl-flex actions">
 					{actions.map(({ text, ...attrs }) => (
 						<CallToAction {...attrs} set:html={text} />
 					))}

package/components/Icons.ts

@@ -84,4 +84,6 @@ export const Icons = {
 		'<path d="M13.78 7.2a3.63 3.63 0 1 0-4.3-3.68h1.78a2.52 2.52 0 0 1 2.52 2.53V7.2zM7.34 18.8h3.92a2.52 2.52 0 0 0 2.52-2.52V8.37h4.17c.58.01 1.04.5 1.03 1.07v6.45a6.3 6.3 0 0 1-6.14 6.43 6.3 6.3 0 0 1-5.5-3.52zm16.1-14.06a2.51 2.51 0 1 1-5.02 0 2.51 2.51 0 0 1 5.02 0zm-3.36 14.24h-.17c.4-1 .59-2.05.57-3.11V9.46c0-.38-.07-.75-.23-1.09h2.69c.58 0 1.06.48 1.06 1.06v5.65a3.9 3.9 0 0 1-3.9 3.9h-.02z"/><path d="M1.02 5.02h10.24c.56 0 1.02.46 1.02 1.03v10.23a1.02 1.02 0 0 1-1.02 1.02H1.02A1.02 1.02 0 0 1 0 16.28V6.04c0-.56.46-1.02 1.02-1.02zm7.81 3.9V7.84H3.45v1.08h2.03v5.57h1.3V8.92h2.05z"/>',
 	instagram:
 		'<path d="M17.3 5.5a1.2 1.2 0 1 0 1.2 1.2 1.2 1.2 0 0 0-1.2-1.2ZM22 7.9a7.6 7.6 0 0 0-.4-2.5 5 5 0 0 0-1.2-1.7 4.7 4.7 0 0 0-1.8-1.2 7.3 7.3 0 0 0-2.4-.4L12 2H7.9a7.3 7.3 0 0 0-2.5.5 4.8 4.8 0 0 0-1.7 1.2 4.7 4.7 0 0 0-1.2 1.8 7.3 7.3 0 0 0-.4 2.4L2 12v4.1a7.3 7.3 0 0 0 .5 2.4 4.7 4.7 0 0 0 1.2 1.8 4.8 4.8 0 0 0 1.8 1.2 7.3 7.3 0 0 0 2.4.4l4.1.1h4.1a7.3 7.3 0 0 0 2.4-.5 4.7 4.7 0 0 0 1.8-1.2 4.8 4.8 0 0 0 1.2-1.7 7.6 7.6 0 0 0 .4-2.5L22 12V7.9ZM20.1 16a5.6 5.6 0 0 1-.3 1.9A3 3 0 0 1 19 19a3.2 3.2 0 0 1-1.1.8 5.6 5.6 0 0 1-1.9.3H8a5.7 5.7 0 0 1-1.9-.3A3.3 3.3 0 0 1 5 19a3 3 0 0 1-.7-1.1 5.5 5.5 0 0 1-.4-1.9l-.1-4V8a5.5 5.5 0 0 1 .4-1.9A3 3 0 0 1 5 5a3.1 3.1 0 0 1 1.1-.8A5.7 5.7 0 0 1 8 3.9l4-.1h4a5.6 5.6 0 0 1 1.9.4A3 3 0 0 1 19 5a3 3 0 0 1 .7 1.1A5.6 5.6 0 0 1 20 8l.1 4v4ZM12 6.9a5.1 5.1 0 1 0 5.1 5.1A5.1 5.1 0 0 0 12 6.9Zm0 8.4a3.3 3.3 0 1 1 3.3-3.3 3.3 3.3 0 0 1-3.3 3.3Z"/>',
+	stackOverflow:
+		'<path d="M15.72 0 14 1.28l6.4 8.58 1.7-1.26L15.73 0zm-3.94 3.42-1.36 1.64 8.22 6.85 1.37-1.64-8.23-6.85zM8.64 7.88l-.91 1.94 9.7 4.52.9-1.94-9.7-4.52zm-1.86 4.86-.44 2.1 10.48 2.2.44-2.1-10.47-2.2zM1.9 15.47V24h19.19v-8.53h-2.13v6.4H4.02v-6.4H1.9zm4.26 2.13v2.13h10.66V17.6H6.15Z"/>',
 };

package/components/MobileMenuToggle.astro

@@ -14,7 +14,7 @@ const t = useTranslations(Astro.props.locale);
 		aria-expanded="false"
 		aria-label={t('menuButton.accessibleLabel')}
 		aria-controls="starlight__sidebar"
-		class="flex md:hidden"
+		class="sl-flex md:sl-hidden"
 	>
 		<Icon name="bars" />
 	</button>

package/components/PrevNextLinks.astro

@@ -15,7 +15,7 @@ const isRtl = dir === 'rtl';
 const t = useTranslations(locale);
 ---
 
-<div class="pagination-links flex" dir={dir}>
+<div class="pagination-links sl-flex" dir={dir}>
 	{
 		prev && (
 			<a href={prev.href} rel="prev">

package/components/RightSidebarPanel.astro

@@ -1,5 +1,5 @@
-<div class="right-sidebar-panel hidden lg:block">
-	<div class="container">
+<div class="right-sidebar-panel sl-hidden lg:sl-block">
+	<div class="sl-container">
 		<slot />
 	</div>
 </div>
@@ -11,7 +11,7 @@
 	.right-sidebar-panel + .right-sidebar-panel {
 		border-top: 1px solid var(--sl-color-hairline);
 	}
-	.container {
+	.sl-container {
 		width: calc(var(--sl-sidebar-width) - 2 * var(--sl-sidebar-pad-x));
 	}
 	.right-sidebar-panel :global(h2) {
@@ -32,7 +32,7 @@
 		color: var(--sl-color-white);
 	}
 	@media (min-width: 72rem) {
-		.container {
+		.sl-container {
 			max-width: calc(
 				(
 					(

package/components/Search.astro

@@ -22,16 +22,16 @@ const pagefindTranslations = {
 			/* The span is `aria-hidden` because it is not shown on small screens. Instead, the icon label is used for accessibility purposes. */
 		}
 		<Icon name="magnifier" label={t('search.label')} />
-		<span class="hidden md:block" aria-hidden="true">{t('search.label')}</span>
-		<Icon name="forward-slash" class="hidden md:block" label={t('search.shortcutLabel')} />
+		<span class="sl-hidden md:sl-block" aria-hidden="true">{t('search.label')}</span>
+		<Icon name="forward-slash" class="sl-hidden md:sl-block" label={t('search.shortcutLabel')} />
 	</button>
 
 	<dialog style="padding:0" aria-label={t('search.label')}>
-		<div class="dialog-frame flex">
+		<div class="dialog-frame sl-flex">
 			{
 				/* TODO: Make the layout of this button flexible to accommodate different word lengths. Currently hard-coded for English: “Cancel” */
 			}
-			<button data-close-modal class="flex md:hidden">
+			<button data-close-modal class="sl-flex md:sl-hidden">
 				{t('search.cancelLabel')}
 			</button>
 			{

package/components/Select.astro

@@ -73,6 +73,7 @@ interface Props {
 
 	option {
 		background-color: var(--sl-color-bg-nav);
+		color: var(--sl-color-gray-1);
 	}
 
 	@media (min-width: 50rem) {

package/components/Sidebar.astro

@@ -12,9 +12,9 @@ interface Props {
 const { sidebar, locale } = Astro.props;
 ---
 
-<div class="sidebar flex">
+<div class="sidebar sl-flex">
 	<SidebarSublist sublist={sidebar} />
-	<div class="mobile-preferences flex md:hidden">
+	<div class="mobile-preferences sl-flex md:sl-hidden">
 		<ThemeSelect {locale} />
 		<LanguageSelect {locale} />
 	</div>

package/components/SidebarSublist.astro

@@ -1,6 +1,7 @@
 ---
 import { flattenSidebar, type SidebarEntry } from '../utils/navigation';
 import Icon from '../user-components/Icon.astro';
+import Badge from './Badge.astro';
 
 interface Props {
 	sublist: SidebarEntry[];
@@ -18,7 +19,13 @@ interface Props {
 						aria-current={entry.isCurrent && 'page'}
 						class:list={{ large: !Astro.props.nested }}
 					>
-						{entry.label}
+						<span>{entry.label}</span>
+						{entry.badge && (
+							<Badge
+								text={entry.badge.text}
+								variant={entry.isCurrent ? 'outline' : entry.badge.variant}
+							/>
+						)}
 					</a>
 				) : (
 					<details
@@ -104,6 +111,10 @@ interface Props {
 		background-color: var(--sl-color-text-accent);
 	}
 
+	a > *:not(:last-child) {
+		margin-inline-end: 0.25em;
+	}
+
 	@media (min-width: 50rem) {
 		.top-level > li + li {
 			margin-top: 0.5rem;

package/components/SiteTitle.astro

@@ -26,7 +26,7 @@ if (config.logo) {
 const href = pathWithBase(Astro.props.locale || '/');
 ---
 
-<a {href} class="site-title flex">
+<a {href} class="site-title sl-flex">
 	{
 		config.logo && logos.dark && (
 			<>

package/components/SocialIcons.astro

@@ -20,6 +20,7 @@ const labels: Record<Platform, string> = {
 	twitch: 'Twitch',
 	microsoftTeams: 'Microsoft Teams',
 	instagram: 'Instagram',
+	stackOverflow: 'Stack Overflow',
 };
 
 const links = Object.entries(config.social || {}).filter(([, url]) => Boolean(url)) as [
@@ -32,7 +33,7 @@ const links = Object.entries(config.social || {}).filter(([, url]) => Boolean(ur
 	links.length > 0 && (
 		<>
 			{links.map(([platform, url]) => (
-				<a href={url} rel="me">
+				<a href={url} rel="me" class="sl-flex">
 					<span class="sr-only">{labels[platform]}</span>
 					<Icon name={platform} />
 				</a>
@@ -44,7 +45,6 @@ const links = Object.entries(config.social || {}).filter(([, url]) => Boolean(ur
 
 <style>
 	a {
-		display: flex;
 		color: var(--sl-color-text-accent);
 	}
 	a:hover {

package/components/TableOfContents/MobileTableOfContents.astro

@@ -16,10 +16,10 @@ const t = useTranslations(locale);
 ---
 
 <mobile-starlight-toc data-min-h={minHeadingLevel} data-max-h={maxHeadingLevel}>
-	<nav aria-labelledby="starlight__on-this-page--mobile" class="lg:hidden">
+	<nav aria-labelledby="starlight__on-this-page--mobile" class="lg:sl-hidden">
 		<details id="starlight__mobile-toc">
-			<summary id="starlight__on-this-page--mobile" class="flex">
-				<div class="toggle flex">
+			<summary id="starlight__on-this-page--mobile" class="sl-flex">
+				<div class="toggle sl-flex">
 					{t('tableOfContents.onThisPage')}
 					<Icon name={'right-caret'} class="caret" size="1rem" />
 				</div>

package/layout/Page.astro

@@ -24,6 +24,7 @@ import SkipLink from '../components/SkipLink.astro';
 import ThemeProvider from '../components/ThemeProvider.astro';
 import PageFrame from '../layout/PageFrame.astro';
 import TwoColumnContent from '../layout/TwoColumnContent.astro';
+import Banner from '../components/Banner.astro';
 
 // Remark component CSS (needs to override `MarkdownContent.astro`)
 import '../style/asides.css';
@@ -92,6 +93,7 @@ const hasHero = Boolean(entry.data.hero);
 				<RightSidebar slot="right-sidebar" {headings} {locale} {tocConfig} />
 				<main data-pagefind-body={entry.slug !== '404'} lang={entryMeta.lang} dir={entryMeta.dir}>
 					{/* TODO: Revisit how this logic flows. */}
+					{entry.data.banner && <Banner {...entry.data.banner} />}
 					{
 						entry.data.hero ? (
 							<ContentPanel>

package/layout/PageFrame.astro

@@ -11,7 +11,7 @@ const { hasSidebar, locale } = Astro.props;
 const t = useTranslations(locale);
 ---
 
-<div class="page flex">
+<div class="page sl-flex">
 	<header class="header"><slot name="header" /></header>
 	{
 		hasSidebar && (

package/layout/TwoColumnContent.astro

@@ -4,7 +4,7 @@ interface Props {
 }
 ---
 
-<div class="lg:flex">
+<div class="lg:sl-flex">
 	{
 		Astro.props.hasToC && (
 			<aside class="right-sidebar-container">

package/package.json

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

package/schema.ts

@@ -3,6 +3,7 @@ import { HeadConfigSchema } from './schemas/head';
 import { PrevNextLinkConfigSchema } from './schemas/prevNextLink';
 import { TableOfContentsSchema } from './schemas/tableOfContents';
 import { Icons } from './components/Icons';
+import { BadgeConfigSchema } from './schemas/badge';
 export { i18nSchema } from './schemas/i18n';
 
 type IconName = keyof typeof Icons;
@@ -147,7 +148,22 @@ export function docsSchema() {
 					 * Prevents this page from being included in autogenerated sidebar groups.
 					 */
 					hidden: z.boolean().default(false),
+					/**
+					 * Adds a badge to the sidebar link.
+					 * Can be a string or an object with a variant and text.
+					 * Variants include 'note', 'tip', 'caution', 'danger', 'success', and 'default'.
+					 * Passing only a string defaults to the 'default' variant which uses the site accent color.
+					 */
+					badge: BadgeConfigSchema(),
 				})
 				.default({}),
+
+			/** Display an announcement banner at the top of this page. */
+			banner: z
+				.object({
+					/** The content of the banner. Supports HTML syntax. */
+					content: z.string(),
+				})
+				.optional(),
 		});
 }

package/schemas/badge.ts

@@ -0,0 +1,20 @@
+import { z } from 'astro/zod';
+
+const badgeSchema = () =>
+	z.object({
+		variant: z.enum(['note', 'danger', 'success', 'caution', 'tip', 'default']).default('default'),
+		text: z.string(),
+	});
+
+export const BadgeConfigSchema = () =>
+	z
+		.union([z.string(), badgeSchema()])
+		.transform((badge) => {
+			if (typeof badge === 'string') {
+				return { variant: 'default' as const, text: badge };
+			}
+			return badge;
+		})
+		.optional();
+
+export type Badge = z.output<ReturnType<typeof badgeSchema>>;

package/style/props.css

@@ -42,6 +42,7 @@
 	--sl-color-bg-nav: var(--sl-color-gray-6);
 	--sl-color-bg-sidebar: var(--sl-color-gray-6);
 	--sl-color-bg-inline-code: var(--sl-color-gray-5);
+	--sl-color-bg-accent: var(--sl-color-accent-high);
 	--sl-color-hairline-light: var(--sl-color-gray-5);
 	--sl-color-hairline: var(--sl-color-gray-6);
 	--sl-color-hairline-shade: var(--sl-color-black);
@@ -148,6 +149,7 @@
 	--sl-color-bg-nav: var(--sl-color-gray-7);
 	--sl-color-bg-sidebar: var(--sl-color-bg);
 	--sl-color-bg-inline-code: var(--sl-color-gray-6);
+	--sl-color-bg-accent: var(--sl-color-accent);
 	--sl-color-hairline-light: var(--sl-color-gray-6);
 	--sl-color-hairline-shade: var(--sl-color-gray-6);
 

package/style/util.css

@@ -10,34 +10,34 @@
 	border-width: 0;
 }
 
-.hidden {
+.sl-hidden {
 	display: none;
 }
-.flex {
+.sl-flex {
 	display: flex;
 }
-.block {
+.sl-block {
 	display: block;
 }
 @media (min-width: 50rem) {
-	.md\:hidden {
+	.md\:sl-hidden {
 		display: none;
 	}
-	.md\:flex {
+	.md\:sl-flex {
 		display: flex;
 	}
-	.md\:block {
+	.md\:sl-block {
 		display: block;
 	}
 }
 @media (min-width: 72rem) {
-	.lg\:hidden {
+	.lg\:sl-hidden {
 		display: none;
 	}
-	.lg\:flex {
+	.lg\:sl-flex {
 		display: flex;
 	}
-	.lg\:block {
+	.lg\:sl-block {
 		display: block;
 	}
 }

package/user-components/Card.astro

@@ -10,8 +10,8 @@ interface Props {
 const { icon, title } = Astro.props;
 ---
 
-<article class="card flex">
-	<p class="title flex">
+<article class="card sl-flex">
+	<p class="title sl-flex">
 		{icon && <Icon name={icon} class="icon" size="1.333em" />}
 		<span set:html={title} />
 	</p>

package/user-components/LinkCard.astro

@@ -11,7 +11,7 @@ const { title, description, ...attributes } = Astro.props;
 ---
 
 <div>
-	<span class="flex stack">
+	<span class="sl-flex stack">
 		<a {...attributes}>
 			<span class="title" set:html={title} />
 		</a>

package/utils/navigation.ts

@@ -7,6 +7,7 @@ import { getLocaleRoutes, type Route } from './routing';
 import { localeToLang, slugToPathname } from './slugs';
 import type { AutoSidebarGroup, SidebarItem, SidebarLinkItem } from './user-config';
 import { ensureLeadingAndTrailingSlashes, ensureTrailingSlash } from './path';
+import type { Badge } from '../schemas/badge';
 
 const DirKey = Symbol('DirKey');
 
@@ -15,6 +16,7 @@ export interface Link {
 	label: string;
 	href: string;
 	isCurrent: boolean;
+	badge: Badge | undefined;
 }
 
 interface Group {
@@ -112,14 +114,14 @@ function linkFromConfig(
 		if (locale) href = '/' + locale + href;
 	}
 	const label = pickLang(item.translations, localeToLang(locale)) || item.label;
-	return makeLink(href, label, currentPathname);
+	return makeLink(href, label, currentPathname, item.badge);
 }
 
 /** Create a link entry. */
-function makeLink(href: string, label: string, currentPathname: string): Link {
+function makeLink(href: string, label: string, currentPathname: string, badge?: Badge): Link {
 	if (!isAbsolute(href)) href = pathWithBase(href);
 	const isCurrent = href === ensureTrailingSlash(currentPathname);
-	return { type: 'link', label, href, isCurrent };
+	return { type: 'link', label, href, isCurrent, badge };
 }
 
 /** Get the segments leading to a page. */
@@ -168,7 +170,8 @@ function linkFromRoute(route: Route, currentPathname: string): Link {
 	return makeLink(
 		slugToPathname(route.slug),
 		route.entry.data.sidebar.label || route.entry.data.title,
-		currentPathname
+		currentPathname,
+		route.entry.data.sidebar.badge
 	);
 }
 
@@ -184,13 +187,17 @@ function getOrder(routeOrDir: Route | Dir): number {
 }
 
 /** Sort a directory’s entries by user-specified order or alphabetically if no order specified. */
-function sortDirEntries(dir: [string, Dir | Route][]): [string, Dir | Route][] {
-	return dir.sort(([, a], [, b]) => {
+function sortDirEntries(
+	dir: [string, Dir | Route][],
+	locale: string | undefined
+): [string, Dir | Route][] {
+	const collator = new Intl.Collator(localeToLang(locale));
+	return dir.sort(([keyA, a], [keyB, b]) => {
 		const [aOrder, bOrder] = [getOrder(a), getOrder(b)];
 		// Pages are sorted by order in ascending order.
 		if (aOrder !== bOrder) return aOrder < bOrder ? -1 : 1;
 		// If two pages have the same order value they will be sorted by their slug.
-		return a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0;
+		return collator.compare(isDir(a) ? keyA : a.slug, isDir(b) ? keyB : b.slug);
 	});
 }
 
@@ -203,7 +210,7 @@ function groupFromDir(
 	locale: string | undefined,
 	collapsed: boolean
 ): Group {
-	const entries = sortDirEntries(Object.entries(dir)).map(([key, dirOrRoute]) =>
+	const entries = sortDirEntries(Object.entries(dir), locale).map(([key, dirOrRoute]) =>
 		dirToItem(dirOrRoute, `${fullPath}/${key}`, key, currentPathname, locale, collapsed)
 	);
 	return {
@@ -235,7 +242,7 @@ function sidebarFromDir(
 	locale: string | undefined,
 	collapsed: boolean
 ) {
-	return sortDirEntries(Object.entries(tree)).map(([key, dirOrRoute]) =>
+	return sortDirEntries(Object.entries(tree), locale).map(([key, dirOrRoute]) =>
 		dirToItem(dirOrRoute, key, key, currentPathname, locale, collapsed)
 	);
 }

package/utils/user-config.ts

@@ -4,6 +4,7 @@ import { HeadConfigSchema } from '../schemas/head';
 import { LogoConfigSchema } from '../schemas/logo';
 import { TableOfContentsSchema } from '../schemas/tableOfContents';
 import { FaviconSchema } from '../schemas/favicon';
+import { BadgeConfigSchema } from '../schemas/badge';
 
 const LocaleSchema = z.object({
 	/** The label for this language to show in UI, e.g. `"English"`, `"العربية"`, or `"简体中文"`. */
@@ -42,6 +43,8 @@ const SidebarGroupSchema = SidebarBaseSchema.extend({
 const SidebarLinkItemSchema = SidebarBaseSchema.extend({
 	/** The link to this item’s content. Can be a relative link to local files or the full URL of an external page. */
 	link: z.string(),
+	/** Adds a badge to the link item */
+	badge: BadgeConfigSchema(),
 });
 export type SidebarLinkItem = z.infer<typeof SidebarLinkItemSchema>;
 
@@ -148,6 +151,7 @@ const UserConfigSchema = z.object({
 				'twitch',
 				'microsoftTeams',
 				'instagram',
+				'stackOverflow',
 			]),
 			// Link to the respective social profile for this site
 			z.string().url()