withastro · delucis · Jan 12, 2025 · Jun 5, 2023 · Jun 5, 2023 · Jun 5, 2023
diff --git a/.changeset/sweet-gorillas-refuse.md b/.changeset/sweet-gorillas-refuse.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": minor
+---
+
+Adds a print stylesheet to improve the appearance of Starlight docs pages when printed
diff --git a/docs/src/components/sidebar-preview.astro b/docs/src/components/sidebar-preview.astro
@@ -54,6 +54,7 @@ function makeEntries(items: SidebarConfig): SidebarEntry[] {
 		background-color: var(--sl-color-bg-sidebar);
 		border: 1px solid var(--sl-color-gray-5);
 		padding: 1rem var(--sl-sidebar-pad-x);
-		max-width: var(--sl-sidebar-width);
+		/* Matches `var(--sl-sidebar-width)`, but hardcoded to avoid being overridden when printing the page. */
+		max-width: 18.75rem;
 	}
 </style>
diff --git a/package.json b/package.json
@@ -38,7 +38,10 @@
     },
     {
       "name": "/_astro/*.css",
-      "path": "examples/basics/dist/_astro/*.css",
+      "path": [
+        "examples/basics/dist/_astro/*.css",
+        "!examples/basics/dist/_astro/print.*.css"
+      ],
       "limit": "14.5 kB",
       "gzip": true
     }

diff --git a/packages/starlight/components/EditLink.astro b/packages/starlight/components/EditLink.astro
@@ -7,7 +7,7 @@ const { editUrl } = Astro.props;
 
 {
 	editUrl && (
-		<a href={editUrl} class="sl-flex">
+		<a href={editUrl} class="sl-flex print:hidden">
 			<Icon name="pencil" size="1.2em" />
 			{Astro.locals.t('page.editLink')}
 		</a>

diff --git a/packages/starlight/components/Header.astro b/packages/starlight/components/Header.astro
@@ -19,10 +19,10 @@ const shouldRenderSearch =
 	<div class="title-wrapper sl-flex">
 		<SiteTitle {...Astro.props} />
 	</div>
-	<div class="sl-flex">
+	<div class="sl-flex print:hidden">
 		{shouldRenderSearch && <Search {...Astro.props} />}
 	</div>
-	<div class="sl-hidden md:sl-flex right-group">
+	<div class="sl-hidden md:sl-flex print:hidden right-group">
 		<div class="sl-flex social-icons">
 			<SocialIcons {...Astro.props} />
 		</div>

diff --git a/packages/starlight/components/MobileMenuToggle.astro b/packages/starlight/components/MobileMenuToggle.astro
@@ -3,7 +3,7 @@ import type { Props } from '../props';
 import Icon from '../user-components/Icon.astro';
 ---
 
-<starlight-menu-button>
+<starlight-menu-button class="print:hidden">
 	<button
 		aria-expanded="false"
 		aria-label={Astro.locals.t('menuButton.accessibleLabel')}

diff --git a/packages/starlight/components/Page.astro b/packages/starlight/components/Page.astro
@@ -31,6 +31,8 @@ import '../style/asides.css';
 // Important that this is the last import so it can override built-in styles.
 import 'virtual:starlight/user-css';
 
+import printHref from '../style/print.css?url&no-inline';
+
 const pagefindEnabled =
 	Astro.props.entry.slug !== '404' &&
 	!Astro.props.entry.slug.endsWith('/404') &&
@@ -75,6 +77,7 @@ if (pagefindEnabled) mainDataAttributes['data-pagefind-body'] = '';
 			}
 		</style>
 		<ThemeProvider {...Astro.props} />
+		<link rel="stylesheet" href={printHref} media="print" />
 	</head>
 	<body>
 		<SkipLink {...Astro.props} />

diff --git a/packages/starlight/components/PageFrame.astro b/packages/starlight/components/PageFrame.astro
@@ -9,7 +9,7 @@ const { hasSidebar } = Astro.props;
 	<header class="header"><slot name="header" /></header>
 	{
 		hasSidebar && (
-			<nav class="sidebar" aria-label={Astro.locals.t('sidebarNav.accessibleLabel')}>
+			<nav class="sidebar print:hidden" aria-label={Astro.locals.t('sidebarNav.accessibleLabel')}>
 				<MobileMenuToggle {...Astro.props} />
 				<div id="starlight__sidebar" class="sidebar-pane">
 					<div class="sidebar-content sl-flex">

diff --git a/packages/starlight/components/Pagination.astro b/packages/starlight/components/Pagination.astro
@@ -7,7 +7,7 @@ const { prev, next } = pagination;
 const isRtl = dir === 'rtl';
 ---
 
-<div class="pagination-links" dir={dir}>
+<div class="pagination-links print:hidden" dir={dir}>
 	{
 		prev && (
 			<a href={prev.href} rel="prev">

diff --git a/packages/starlight/components/SiteTitle.astro b/packages/starlight/components/SiteTitle.astro
@@ -10,7 +10,7 @@ const { siteTitle, siteTitleHref } = Astro.props;
 		config.logo && logos.dark && (
 			<>
 				<img
-					class:list={{ 'light:sl-hidden': !('src' in config.logo) }}
+					class:list={{ 'light:sl-hidden print:hidden': !('src' in config.logo) }}
 					alt={config.logo.alt}
 					src={logos.dark.src}
 					width={logos.dark.width}
@@ -19,7 +19,7 @@ const { siteTitle, siteTitleHref } = Astro.props;
 				{/* Show light alternate if a user configure both light and dark logos. */}
 				{!('src' in config.logo) && (
 					<img
-						class="dark:sl-hidden"
+						class="dark:sl-hidden print:block"
 						alt={config.logo.alt}
 						src={logos.light?.src}
 						width={logos.light?.width}

diff --git a/packages/starlight/components/TwoColumnContent.astro b/packages/starlight/components/TwoColumnContent.astro
@@ -5,7 +5,7 @@ import type { Props } from '../props';
 <div class="lg:sl-flex">
 	{
 		Astro.props.toc && (
-			<aside class="right-sidebar-container">
+			<aside class="right-sidebar-container print:hidden">
 				<div class="right-sidebar">
 					<slot name="right-sidebar" />
 				</div>

diff --git a/packages/starlight/style/print.css b/packages/starlight/style/print.css
@@ -0,0 +1,140 @@
+@media print {
+	/**
+	This is increased in specificity so it works even when injected into pages before regular styles.
+	TODO: Just use `:root` once we move to @layer.
+	Same goes for the use of `!important` in this file.
+	*/
+	:root[data-theme]:is(:root) {
+		/* Colours (light mode) */
+		--sl-color-white: hsl(224, 10%, 10%);
+		--sl-color-gray-1: hsl(224, 14%, 16%);
+		--sl-color-gray-2: hsl(224, 10%, 23%);
+		--sl-color-gray-3: hsl(224, 7%, 36%);
+		--sl-color-gray-4: hsl(224, 6%, 56%);
+		--sl-color-gray-5: hsl(224, 6%, 77%);
+		--sl-color-gray-6: hsl(224, 20%, 94%);
+		--sl-color-gray-7: hsl(224, 19%, 97%);
+		--sl-color-black: hsl(0, 0%, 100%);
+
+		--sl-color-orange-high: hsl(var(--sl-hue-orange), 80%, 25%);
+		--sl-color-orange: hsl(var(--sl-hue-orange), 90%, 60%);
+		--sl-color-orange-low: hsl(var(--sl-hue-orange), 90%, 88%);
+		--sl-color-green-high: hsl(var(--sl-hue-green), 80%, 22%);
+		--sl-color-green: hsl(var(--sl-hue-green), 90%, 46%);
+		--sl-color-green-low: hsl(var(--sl-hue-green), 85%, 90%);
+		--sl-color-blue-high: hsl(var(--sl-hue-blue), 80%, 30%);
+		--sl-color-blue: hsl(var(--sl-hue-blue), 90%, 60%);
+		--sl-color-blue-low: hsl(var(--sl-hue-blue), 88%, 90%);
+		--sl-color-purple-high: hsl(var(--sl-hue-purple), 90%, 30%);
+		--sl-color-purple: hsl(var(--sl-hue-purple), 90%, 60%);
+		--sl-color-purple-low: hsl(var(--sl-hue-purple), 80%, 90%);
+		--sl-color-red-high: hsl(var(--sl-hue-red), 80%, 30%);
+		--sl-color-red: hsl(var(--sl-hue-red), 90%, 60%);
+		--sl-color-red-low: hsl(var(--sl-hue-red), 80%, 90%);
+
+		--sl-color-accent-high: hsl(234, 80%, 30%);
+		--sl-color-accent: hsl(234, 90%, 60%);
+		--sl-color-accent-low: hsl(234, 88%, 90%);
+
+		--sl-color-text-accent: var(--sl-color-accent);
+		--sl-color-text-invert: var(--sl-color-black);
+		--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);
+
+		--sl-color-backdrop-overlay: hsla(225, 9%, 36%, 0.66);
+
+		/* Disable shadows when printing. */
+		--sl-shadow-sm: none;
+		--sl-shadow-md: none;
+		--sl-shadow-lg: none;
+	}
+
+	/* Utility classes for controlling element visibility when printing. */
+	.print\:hidden {
+		display: none !important;
+	}
+	.print\:flex {
+		display: flex !important;
+	}
+	.print\:block {
+		display: block !important;
+	}
+
+	/* Page layout tweaks. */
+	main {
+		padding-bottom: 0 !important;
+	}
+	main > .content-panel {
+		padding-block-start: 0 !important;
+	}
+	.content-panel + .content-panel {
+		border: 0 !important;
+	}
+	/* layout/PageFrame.astro */
+	.page > header {
+		position: relative !important;
+	}
+	.page > .main-frame {
+		padding-top: 0;
+		padding-inline-start: 0;
+	}
+	/* layout/TwoColumnContent.astro */
+	.main-pane {
+		--sl-sidebar-width: 0px !important;
+		--sl-content-width: 100% !important;
+	}
+
+	/* components/MarkdownContent.astro */
+	.sl-markdown-content :is(h1, h2, h3, h4, h5, h6) {
+		break-after: avoid;
+	}
+	.sl-markdown-content :is(p, li) {
+		orphans: 2;
+		widows: 2;
+	}
+	.sl-markdown-content pre {
+		overflow-x: hidden !important;
+		white-space: pre-wrap !important;
+	}
+	.sl-markdown-content .expressive-code {
+		break-inside: avoid;
+	}
+	/* Inline code */
+	.sl-markdown-content code:not(:where(.not-content *)) {
+		background-color: transparent !important;
+		padding: 0 !important;
+		margin-block: unset !important;
+		font-size: 0.9375em !important;
+	}
+
+	/* user-components/FileTree.astro */
+	starlight-file-tree {
+		break-inside: avoid;
+	}
+	starlight-file-tree .highlight {
+		outline: 3px solid var(--sl-color-accent-low);
+		color: var(--sl-color-text) !important;
+		background-color: transparent !important;
+	}
+
+	/* user-components/Aside.astro */
+	.starlight-aside {
+		break-inside: avoid;
+	}
+
+	/* user-components/LinkButton.astro */
+	.sl-link-button.primary {
+		background: transparent !important;
+		border-color: var(--sl-color-white) !important;
+		color: var(--sl-color-white) !important;
+	}
+
+	/* user-components/Tabs.astro */
+	starlight-tabs {
+		break-inside: avoid;
+	}
+}
diff --git a/packages/starlight/user-components/FileTree.astro b/packages/starlight/user-components/FileTree.astro
@@ -47,15 +47,15 @@ const html = processFileTree(fileTreeHtml, Astro.locals.t('fileTree.directory'))
 	starlight-file-tree :global(.directory > details > summary:hover .tree-icon) {
 		cursor: pointer;
 		color: var(--sl-color-text-accent);
-		fill: var(--sl-color-text-accent);
+		fill: currentColor;
 	}
 
 	starlight-file-tree :global(.directory > details > summary:hover ~ ul) {
 		border-color: var(--sl-color-gray-4);
 	}
 
 	starlight-file-tree :global(.directory > details > summary:hover .highlight .tree-icon) {
-		fill: var(--sl-color-text-invert);
+		fill: currentColor;
 	}
 
 	starlight-file-tree :global(ul) {
@@ -129,6 +129,6 @@ const html = processFileTree(fileTreeHtml, Astro.locals.t('fileTree.directory'))
 	}
 
 	starlight-file-tree :global(.highlight svg.tree-icon) {
-		fill: var(--sl-color-text-invert);
+		fill: currentColor;
 	}
 </style>