diff --git a/.changeset/chilled-pots-eat.md b/.changeset/chilled-pots-eat.md new file mode 100644 index 0000000000..e5c56b35d5 --- /dev/null +++ b/.changeset/chilled-pots-eat.md @@ -0,0 +1,5 @@ +--- +'@astrojs/starlight': minor +--- + +Adds `` component for visually distinct and emphasized call to action links diff --git a/.changeset/thirty-students-sit.md b/.changeset/thirty-students-sit.md new file mode 100644 index 0000000000..40deed7555 --- /dev/null +++ b/.changeset/thirty-students-sit.md @@ -0,0 +1,16 @@ +--- +'@astrojs/starlight': minor +--- + +Changes the hero component action button default [variant](https://starlight.astro.build/reference/frontmatter/#heroconfig) from `minimal` to `primary`. + +If you want to preserve the previous behavior, hero component action button previously declared without a `variant` will need to be updated to include the `variant` property with the value `minimal`. + +```diff +hero: + actions: + - text: View on GitHub + link: https://github.com/astronaut/my-project + icon: external ++ variant: minimal +``` diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx index b01050f0e9..e9163dec0d 100644 --- a/docs/src/content/docs/guides/components.mdx +++ b/docs/src/content/docs/guides/components.mdx @@ -222,6 +222,37 @@ import { LinkCard } from '@astrojs/starlight/components'; +### Link Buttons + +Use the `` component for visually distinct and emphasized call to action links best suited to sparingly direct users to the most relevant or actionable content at the end of a section. + +A `` requires an [`href`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href) attribute and optionally accepts other link attributes such as `target`. + +The `icon` attribute can optionally be set to the name of [one of Starlight's built-in icons](#all-icons) to include an icon next to the text. +The `iconPlacement` attribute can be used to place the icon before the text by setting it to `start` (defaults to `end`). + +Customize the appearance of the link button using the `variant` attribute, which can be set to `primary` (the default), `secondary`, or `minimal`. + +```mdx +# src/content/docs/example.mdx + +import { LinkButton } from '@astrojs/starlight/components'; + +Get started + + Related: Astro + +``` + +The above code generates the following on the page: + +import { LinkButton } from '@astrojs/starlight/components'; + +Get started + + Related: Astro + + ### Asides Asides (also known as “admonitions” or “callouts”) are useful for displaying secondary information alongside a page’s main content. diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 79c5ba60c9..d1dee8feee 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -15,10 +15,10 @@ hero: actions: - text: Get started icon: right-arrow - variant: primary link: /getting-started/ - text: View on GitHub icon: external + variant: minimal link: https://github.com/withastro/starlight --- @@ -69,8 +69,9 @@ import Testimonial from '~/components/testimonial.astro'; Starlight is our go-to example of a great DX: the speed, convenience, and attention to details is inspiring. It takes care of the tech and the looks, so you can focus on your content 👏 - + StackBlitz team absolutely loves it! + ; }>; } diff --git a/packages/starlight/components.ts b/packages/starlight/components.ts index e564b62b73..1c207f69db 100644 --- a/packages/starlight/components.ts +++ b/packages/starlight/components.ts @@ -7,4 +7,5 @@ export { default as TabItem } from './user-components/TabItem.astro'; export { default as LinkCard } from './user-components/LinkCard.astro'; export { default as Steps } from './user-components/Steps.astro'; export { default as FileTree } from './user-components/FileTree.astro'; +export { default as LinkButton } from './user-components/LinkButton.astro'; export { Code } from 'astro-expressive-code/components'; diff --git a/packages/starlight/components/CallToAction.astro b/packages/starlight/components/CallToAction.astro deleted file mode 100644 index 591ffab086..0000000000 --- a/packages/starlight/components/CallToAction.astro +++ /dev/null @@ -1,51 +0,0 @@ ---- -import type { HTMLAttributes } from 'astro/types'; -import Icon from '../user-components/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 }; - attrs?: Omit, 'href'>; -} - -const { link, variant, icon } = Astro.props; -const { class: customClass, ...attrs } = Astro.props.attrs || {}; ---- - - - - {icon?.type === 'icon' && } - {icon?.type === 'raw' && } - - - diff --git a/packages/starlight/components/Hero.astro b/packages/starlight/components/Hero.astro index f763ce227e..51be009ab4 100644 --- a/packages/starlight/components/Hero.astro +++ b/packages/starlight/components/Hero.astro @@ -2,7 +2,7 @@ import { Image } from 'astro:assets'; import { PAGE_TITLE_ID } from '../constants'; import type { Props } from '../props'; -import CallToAction from './CallToAction.astro'; +import LinkButton from '../user-components/LinkButton.astro'; const { data } = Astro.props.entry; const { title = data.title, tagline, image, actions = [] } = data.hero || {}; @@ -50,8 +50,11 @@ if (image) { { actions.length > 0 && (
- {actions.map(({ text, ...attrs }) => ( - + {actions.map(({ attrs, icon, link: href, text, variant }) => ( + + {text} + {icon?.html && } + ))}
) diff --git a/packages/starlight/package.json b/packages/starlight/package.json index 059b2ba8ac..bfbe6406f4 100644 --- a/packages/starlight/package.json +++ b/packages/starlight/package.json @@ -51,10 +51,6 @@ "types": "./components/Sidebar.astro.tsx", "import": "./components/Sidebar.astro" }, - "./components/CallToAction.astro": { - "types": "./components/CallToAction.astro.tsx", - "import": "./components/CallToAction.astro" - }, "./components/MarkdownContent.astro": { "types": "./components/MarkdownContent.astro.tsx", "import": "./components/MarkdownContent.astro" diff --git a/packages/starlight/schemas/hero.ts b/packages/starlight/schemas/hero.ts index 0c335124bb..6ecc50df13 100644 --- a/packages/starlight/schemas/hero.ts +++ b/packages/starlight/schemas/hero.ts @@ -49,8 +49,8 @@ export const HeroSchema = ({ image }: SchemaContext) => text: z.string(), /** Value for the link’s `href` attribute, e.g. `/page` or `https://mysite.com`. */ link: z.string(), - /** Button style to use. One of `primary`, `secondary`, or `minimal` (the default). */ - variant: z.enum(['primary', 'secondary', 'minimal']).default('minimal'), + /** Button style to use. One of `primary` (the default), `secondary`, or `minimal`. */ + variant: z.enum(['primary', 'secondary', 'minimal']).default('primary'), /** * An optional icon to display alongside the link text. * Can be an inline `` or the name of one of Starlight’s built-in icons. diff --git a/packages/starlight/style/markdown.css b/packages/starlight/style/markdown.css index d0e2248eb1..b5388c66cf 100644 --- a/packages/starlight/style/markdown.css +++ b/packages/starlight/style/markdown.css @@ -62,10 +62,10 @@ font-size: var(--sl-text-h6); } -.sl-markdown-content a:not(:where(.not-content *)) { +.sl-markdown-content a:not(:where(:is(.not-content, .not-content *))) { color: var(--sl-color-text-accent); } -.sl-markdown-content a:hover:not(:where(.not-content *)) { +.sl-markdown-content a:hover:not(:where(:is(.not-content, .not-content *))) { color: var(--sl-color-white); } diff --git a/packages/starlight/user-components/LinkButton.astro b/packages/starlight/user-components/LinkButton.astro new file mode 100644 index 0000000000..c6beec9987 --- /dev/null +++ b/packages/starlight/user-components/LinkButton.astro @@ -0,0 +1,72 @@ +--- +import type { HTMLAttributes } from 'astro/types'; +import { Icons } from '../components/Icons'; +import Icon from './Icon.astro'; + +interface Props extends Omit, 'href'> { + href: string | URL; + icon?: keyof typeof Icons | undefined; + iconPlacement?: 'start' | 'end' | undefined; + variant?: 'primary' | 'secondary' | 'minimal'; +} + +const { + class: className, + icon, + iconPlacement = 'end', + variant = 'primary', + ...attrs +} = Astro.props; +--- + + + {icon && iconPlacement === 'start' && } + + {icon && iconPlacement === 'end' && } + + +