From ccb919d6580955e3428430a704f4a33fbc55a78d Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Fri, 2 Jun 2023 17:37:31 +0200 Subject: Add hero component support (#103) --- .changeset/eighty-rats-pay.md | 5 + .github/workflows/ci.yml | 2 + docs/astro.config.mjs | 1 + docs/src/assets/hero-star.webp | Bin 0 -> 114506 bytes docs/src/assets/landing.css | 25 ++++ docs/src/content/docs/de/index.mdx | 15 ++- docs/src/content/docs/index.mdx | 15 ++- docs/src/content/docs/reference/frontmatter.md | 70 +++++++++-- packages/starlight/components/CallToAction.astro | 51 ++++++++ packages/starlight/components/Hero.astro | 136 ++++++++++++++++++++++ packages/starlight/components/Icon.astro | 7 +- packages/starlight/components/Icons.ts | 2 + packages/starlight/components/SkipLink.astro | 2 + packages/starlight/index.astro | 38 +++--- packages/starlight/schema.ts | 141 ++++++++++++++++++----- packages/starlight/style/props.css | 1 + 16 files changed, 451 insertions(+), 60 deletions(-) create mode 100644 .changeset/eighty-rats-pay.md create mode 100644 docs/src/assets/hero-star.webp create mode 100644 docs/src/assets/landing.css create mode 100644 packages/starlight/components/CallToAction.astro create mode 100644 packages/starlight/components/Hero.astro diff --git a/.changeset/eighty-rats-pay.md b/.changeset/eighty-rats-pay.md new file mode 100644 index 00000000..2d629065 --- /dev/null +++ b/.changeset/eighty-rats-pay.md @@ -0,0 +1,5 @@ +--- +"@astrojs/starlight": patch +--- + +Support adding a hero section to pages diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ee36920f..2435a8e9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -35,6 +35,8 @@ jobs: - name: Build docs site working-directory: ./docs run: pnpm build + env: + NO_GRADIENTS: true - name: Run accessibility audit working-directory: ./docs diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 83b334fd..2c174122 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -29,6 +29,7 @@ export default defineConfig({ }, }, ], + customCss: process.env.NO_GRADIENTS ? [] : ['/src/assets/landing.css'], locales: { root: { label: 'English', lang: 'en' }, de: { label: 'Deutsch', lang: 'de' }, diff --git a/docs/src/assets/hero-star.webp b/docs/src/assets/hero-star.webp new file mode 100644 index 00000000..0d9ef67f Binary files /dev/null and b/docs/src/assets/hero-star.webp differ diff --git a/docs/src/assets/landing.css b/docs/src/assets/landing.css new file mode 100644 index 00000000..244cbc53 --- /dev/null +++ b/docs/src/assets/landing.css @@ -0,0 +1,25 @@ +:root { + --purple-hsl: 255, 60%, 60%; + --overlay-blurple: hsla(var(--purple-hsl), 0.2); +} + +:root[data-theme='light'] { + --purple-hsl: 255, 85%, 65%; +} + +[data-has-hero] .page { + background: linear-gradient(215deg, var(--overlay-blurple), transparent 40%), + radial-gradient(var(--overlay-blurple), transparent 40%) no-repeat -60vw -40vh / + 105vw 200vh; +} + +[data-has-hero] header { + border-bottom: 1px solid transparent; + background-color: transparent; + -webkit-backdrop-filter: blur(16px); + backdrop-filter: blur(16px); +} + +[data-has-hero] .hero > img { + filter: drop-shadow(0 0 3rem hsla(var(--purple-hsl), 0.25)); +} diff --git a/docs/src/content/docs/de/index.mdx b/docs/src/content/docs/de/index.mdx index f710c658..9c1fea1e 100644 --- a/docs/src/content/docs/de/index.mdx +++ b/docs/src/content/docs/de/index.mdx @@ -1,7 +1,20 @@ --- -title: Wilkommen, Welt +title: Starlight 🌟 Einfache Dokumentations-Websites mit Astro description: Erstelle schöne, leistungsstarke Dokumentations-Websites mit Starlight und Astro. template: splash +hero: + title: Bringe deine Dokumentation mit Starlight zum Leuchten + tagline: Alles, was du brauchst, um eine erstklassige Dokumentations-Website zu erstellen. Schnell, barrierefrei und einfach zu bedienen. + image: + file: ../../../assets/hero-star.webp + actions: + - text: Los geht's + icon: right-arrow + variant: primary + link: /de/getting-started/ + - text: Auf GitHub + icon: external + link: https://github.com/withastro/starlight --- :::caution[Laufende Arbeiten] diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 56d15de8..6fd00133 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -1,7 +1,20 @@ --- -title: Welcome, world +title: Starlight 🌟 Build documentation sites with Astro description: Starlight helps you build beautiful, high-performance documentation websites with Astro. template: splash +hero: + title: Make your docs shine with Starlight + tagline: Everything you need to build a stellar documentation website. Fast, accessible, and easy-to-use. + image: + file: ../../assets/hero-star.webp + actions: + - text: Get started + icon: right-arrow + variant: primary + link: /getting-started/ + - text: View on GitHub + icon: external + link: https://github.com/withastro/starlight --- :::caution[Work in progress] diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md index 4d947100..7d1f04cc 100644 --- a/docs/src/content/docs/reference/frontmatter.md +++ b/docs/src/content/docs/reference/frontmatter.md @@ -34,15 +34,6 @@ The page description is used for page metadata and will be picked up by search e Overrides the [global `editLink` config](/reference/configuration/#editlink). Set to `false` to disable the “Edit page” link for a specific page or provide an alternative URL where the content of this page is editable. -### `template` - -**type:** `'doc' | 'splash'` -**default:** `'doc'` - -Set the layout template for this page. -Pages use the `'doc'` layout by default. -Set to `'splash'` to use a wider layout without any sidebars designed for landing pages. - ### `head` **type:** [`HeadConfig[]`](/reference/configuration/#headconfig) @@ -65,3 +56,64 @@ head: Overrides the [global `tableOfContents` config](/reference/configuration/#tableofcontents). Customize the heading levels to be included or set to `false` to hide the table of contents on this page. + +### `template` + +**type:** `'doc' | 'splash'` +**default:** `'doc'` + +Set the layout template for this page. +Pages use the `'doc'` layout by default. +Set to `'splash'` to use a wider layout without any sidebars designed for landing pages. + +### `hero` + +**type:** [`HeroConfig`](#heroconfig) + +Add a hero component to the top of this page. Works well with `template: splash`. + +For example, this config shows some common options, including loading an image from your repository. + +```md +--- +title: My Home Page +template: splash +hero: + title: 'My Project: Stellar Stuff Sooner' + tagline: Take your stuff to the moon and back in the blink of an eye. + image: + alt: A glittering, brightly colored logo + file: ../../assets/logo.png + actions: + - text: Tell me more + link: /getting-started/ + icon: right-arrow + variant: primary + - text: View on GitHub + link: https://github.com/astronaut/my-project + icon: external +--- +``` + +#### `HeroConfig` + +```ts +interface HeroConfig { + title?: string; + tagline?: string; + image?: { + alt?: string; + // Relative path to an image in your repository. + file?: string; + // Raw HTML to use in the image slot. + // Could be a custom `` tag or inline ``. + html?: string; + }; + actions?: Array<{ + text: string; + link: string; + variant: 'primary' | 'secondary' | 'minimal'; + icon: string; + }>; +} +``` diff --git a/packages/starlight/components/CallToAction.astro b/packages/starlight/components/CallToAction.astro new file mode 100644 index 00000000..977516ca --- /dev/null +++ b/packages/starlight/components/CallToAction.astro @@ -0,0 +1,51 @@ +--- +import Icon from './Icon.astro'; +import type { Icons } from './Icons'; + +interface Props { + variant: 'primary' | 'secondary' | 'minimal'; + link: string; + icon?: + | undefined + | { type: 'icon'; name: keyof typeof Icons } + | { type: 'raw'; html: string }; +} + +const { link, variant, icon } = Astro.props; +--- + + + + {icon?.type === 'icon' && } + {icon?.type === 'raw' && } + + + diff --git a/packages/starlight/components/Hero.astro b/packages/starlight/components/Hero.astro new file mode 100644 index 00000000..36335b42 --- /dev/null +++ b/packages/starlight/components/Hero.astro @@ -0,0 +1,136 @@ +--- +import type { CollectionEntry } from 'astro:content'; +import { Image } from 'astro:assets'; +import CallToAction from './CallToAction.astro'; + +interface Props { + fallbackTitle: string; + hero: NonNullable['data']['hero']>; +} + +const { + title = Astro.props.fallbackTitle, + tagline, + image, + actions, +} = Astro.props.hero; +--- + +
+ { + image?.file ? ( + {image.alt} + ) : ( + image?.html &&
+ ) + } +
+
+

+ {tagline &&
} +
+ { + actions.length > 0 && ( +
+ {actions.map(({ text, ...attrs }) => ( + + ))} +
+ ) + } +

+
+ + diff --git a/packages/starlight/components/Icon.astro b/packages/starlight/components/Icon.astro index a8a54c87..6fed52e4 100644 --- a/packages/starlight/components/Icon.astro +++ b/packages/starlight/components/Icon.astro @@ -9,7 +9,7 @@ interface Props { class?: string; } -const { name, label, size = '1em', color = '' } = Astro.props; +const { name, label, size = '1em', color } = Astro.props; const a11yAttrs = label ? ({ 'aria-label': label } as const) : ({ 'aria-hidden': 'true' } as const); @@ -22,13 +22,12 @@ const a11yAttrs = label height="16" viewBox="0 0 24 24" fill="currentColor" - style={`--sl-icon-color: ${color}; --sl-icon-size: ${size};`} set:html={Icons[name]} /> -