From 2c8fb59f6236c7e6ab29350a88d15403aaf0aa04 Mon Sep 17 00:00:00 2001 From: HiDeoo <494699+HiDeoo@users.noreply.github.com> Date: Tue, 21 Nov 2023 00:07:20 +0100 Subject: [PATCH 1/7] docs: add more text markers and frame informations --- docs/src/content/docs/guides/components.mdx | 4 ++ .../content/docs/guides/css-and-tailwind.mdx | 6 +-- .../src/content/docs/guides/customization.mdx | 49 ++++++++++--------- docs/src/content/docs/guides/i18n.mdx | 10 ++-- docs/src/content/docs/guides/sidebar.mdx | 33 ++++++++----- docs/src/content/docs/manual-setup.mdx | 2 +- .../content/docs/reference/configuration.mdx | 24 +++++++-- .../src/content/docs/reference/frontmatter.md | 21 +++++++- docs/src/content/docs/reference/overrides.md | 1 + 9 files changed, 101 insertions(+), 49 deletions(-) diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx index ee12879528a..a86d5ffe326 100644 --- a/docs/src/content/docs/guides/components.mdx +++ b/docs/src/content/docs/guides/components.mdx @@ -61,6 +61,7 @@ You can display a tabbed interface using the `` and `` components Each `` must have a `label` to display to users. ```mdx +# src/content/docs/index.mdx import { Tabs, TabItem } from '@astrojs/starlight/components'; @@ -86,6 +87,7 @@ Wrap multiple cards in the `` component to display cards side-by-side A `` requires a `title` and can optionally include an `icon` attribute set to the name of [one of Starlight’s built-in icons](#all-icons). ```mdx +# src/content/docs/index.mdx import { Card, CardGrid } from '@astrojs/starlight/components'; Interesting content you want to highlight. @@ -134,6 +136,7 @@ A `` requires a `title` and an [`href`](https://developer.mozilla.org/ Group multiple `` components in `` to display cards side-by-side when there’s enough space. ```mdx +# src/content/docs/index.mdx import { LinkCard, CardGrid } from '@astrojs/starlight/components'; ` requires a [`name`](#all-icons) and can optionally include a `label`, `size`, and `color` attribute. ```mdx +# src/content/docs/index.mdx import { Icon } from '@astrojs/starlight/components'; diff --git a/docs/src/content/docs/guides/css-and-tailwind.mdx b/docs/src/content/docs/guides/css-and-tailwind.mdx index 440df5a66ce..e2c7b513ce3 100644 --- a/docs/src/content/docs/guides/css-and-tailwind.mdx +++ b/docs/src/content/docs/guides/css-and-tailwind.mdx @@ -22,7 +22,7 @@ Customize the styles applied to your Starlight site by providing additional CSS 2. Add the path to your CSS file to Starlight’s `customCss` array in `astro.config.mjs`: - ```js + ```diff lang="js" // astro.config.mjs import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; @@ -32,8 +32,8 @@ Customize the styles applied to your Starlight site by providing additional CSS starlight({ title: 'Docs With Custom CSS', customCss: [ - // Relative path to your custom CSS file - './src/styles/custom.css', + + // Relative path to your custom CSS file + + './src/styles/custom.css', ], }), ], diff --git a/docs/src/content/docs/guides/customization.mdx b/docs/src/content/docs/guides/customization.mdx index adfd02cdbd7..89f75bfb249 100644 --- a/docs/src/content/docs/guides/customization.mdx +++ b/docs/src/content/docs/guides/customization.mdx @@ -27,7 +27,7 @@ Adding a custom logo to the site header is a quick way to add your individual br 2. Add the path to your logo as Starlight’s [`logo.src`](/reference/configuration/#logo) option in `astro.config.mjs`: - ```js + ```diff lang="js" // astro.config.mjs import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; @@ -37,7 +37,7 @@ Adding a custom logo to the site header is a quick way to add your individual br starlight({ title: 'Docs With My Logo', logo: { - src: './src/assets/my-logo.svg', + + src: './src/assets/my-logo.svg', }, }), ], @@ -48,7 +48,8 @@ By default, the logo will be displayed alongside your site’s `title`. If your logo image already includes the site title, you can visually hide the title text by setting the `replacesTitle` option. The `title` text will still be included for screen readers so that the header remains accessible. -```js +```js {6} +// astro.config.mjs starlight({ title: 'Docs With My Logo', logo: { @@ -77,12 +78,13 @@ You can display different versions of your logo in light and dark modes. 2. Add the path to your logo variants as the `light` and `dark` options instead of `src` in `astro.config.mjs`: - ```js + ```diff lang="js" + // astro.config.mjs starlight({ title: 'Docs With My Logo', logo: { - light: './src/assets/light-logo.svg', - dark: './src/assets/dark-logo.svg', + + light: './src/assets/light-logo.svg', + + dark: './src/assets/dark-logo.svg', }, }), ``` @@ -91,7 +93,7 @@ You can display different versions of your logo in light and dark modes. Starlight has built-in support for generating a sitemap. Enable sitemap generation by setting your URL as `site` in `astro.config.mjs`: -```js +```js {4} // astro.config.mjs export default defineConfig({ @@ -107,7 +109,7 @@ By default, Starlight pages use a layout with a global navigation sidebar and a You can apply a wider page layout without sidebars by setting [`template: splash`](/reference/frontmatter/#template) in a page’s frontmatter. This works particularly well for landing pages and you can see it in action on the [homepage of this site](/). -```md +```md {5} --- # src/content/docs/index.md @@ -126,7 +128,7 @@ By default, `

` and `

` headings are included in the table of contents. Ch -```md +```md {4-6} --- # src/content/docs/example.md title: Page with only H2s in the table of contents @@ -139,7 +141,7 @@ tableOfContents: -```js +```js {7} // astro.config.mjs defineConfig({ @@ -160,7 +162,7 @@ Disable the table of contents entirely by setting the `tableOfContents` option t -```md +```md {4} --- # src/content/docs/example.md title: Page without a table of contents @@ -171,7 +173,7 @@ tableOfContents: false -```js +```js {7} // astro.config.mjs defineConfig({ @@ -194,7 +196,7 @@ Starlight has built-in support for adding links to your social media accounts to You can find a full list of supported link icons in the [Configuration Reference](/reference/configuration/#social). Let us know on GitHub or Discord if you need support for another service! -```js +```js {9-12} // astro.config.mjs import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; @@ -230,7 +232,7 @@ If your Starlight project is not in the root of your repository, include the pat This example shows the edit link configured for the Starlight docs, which live in the `docs/` subdirectory on the `main` branch of the `withastro/starlight` repository on GitHub: -```js +```js {9-11} // astro.config.mjs import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; @@ -265,8 +267,9 @@ You can customize this by adding a `404.md` (or `404.mdx`) file to your `src/con You can use all of Starlight’s page layout and customization techniques in your 404 page. For example, the default 404 page uses the [`splash` template](#page-layout) and [`hero`](/reference/frontmatter/#hero) component in frontmatter: -```md +```md {4,6-8} --- +# src/content/docs/404.md title: '404' template: splash editUrl: false @@ -321,7 +324,7 @@ To use Google Fonts, follow the [Fontsource set-up guide](#set-up-a-fontsource-f 3. Add the path to your `font-face.css` file to Starlight’s `customCss` array in `astro.config.mjs`: - ```js + ```diff lang="js" // astro.config.mjs import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; @@ -331,8 +334,8 @@ To use Google Fonts, follow the [Fontsource set-up guide](#set-up-a-fontsource-f starlight({ title: 'Docs With a Custom Typeface', customCss: [ - // Relative path to your @font-face CSS file. - './src/fonts/font-face.css', + + // Relative path to your @font-face CSS file. + + './src/fonts/font-face.css', ], }), ], @@ -380,7 +383,7 @@ It provides npm modules you can install for the fonts you want to use and includ 3. Add Fontsource CSS files to Starlight’s `customCss` array in `astro.config.mjs`: - ```js + ```diff lang="js" // astro.config.mjs import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; @@ -390,9 +393,9 @@ It provides npm modules you can install for the fonts you want to use and includ starlight({ title: 'Docs With a Custom Typeface', customCss: [ - // Fontsource files for to regular and semi-bold font weights. - '@fontsource/ibm-plex-serif/400.css', - '@fontsource/ibm-plex-serif/600.css', + + // Fontsource files for to regular and semi-bold font weights. + + '@fontsource/ibm-plex-serif/400.css', + + '@fontsource/ibm-plex-serif/600.css', ], }), ], @@ -406,7 +409,7 @@ It provides npm modules you can install for the fonts you want to use and includ To apply the font you set up to your site, use your chosen font’s name in a [custom CSS file](/guides/css-and-tailwind/#custom-css-styles). For example, to override Starlight’s default font everywhere, set the `--sl-font` custom property: -```css +```css {4} /* src/styles/custom.css */ :root { diff --git a/docs/src/content/docs/guides/i18n.mdx b/docs/src/content/docs/guides/i18n.mdx index 42166c7a9b0..1c9ae47782c 100644 --- a/docs/src/content/docs/guides/i18n.mdx +++ b/docs/src/content/docs/guides/i18n.mdx @@ -11,7 +11,7 @@ Starlight provides built-in support for multilingual sites, including routing, f 1. Tell Starlight about the languages you support by passing [`locales`](/reference/configuration/#locales) and [`defaultLocale`](/reference/configuration/#defaultlocale) to the Starlight integration: - ```js + ```js {9-26} // astro.config.mjs import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; @@ -69,7 +69,7 @@ You can use a “root” locale to serve a language without any i18n prefix in i To set a root locale, use the `root` key in your `locales` config. If the root locale is also the default locale for your content, remove `defaultLocale` or set it to `'root'`. -```js +```js {9,11-14} // astro.config.mjs import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; @@ -111,7 +111,7 @@ When using a `root` locale, keep pages for that language directly in `src/conten By default, Starlight is a monolingual (English) site. To create a single language site in another language, set it as the `root` in your `locales` config: -```js +```diff lang="js" {10-13} // astro.config.mjs import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; @@ -152,14 +152,14 @@ You can provide translations for additional languages you support — or overrid 1. Configure the `i18n` data collection in `src/content/config.ts` if it isn’t configured already: - ```js + ```diff lang="js" ins=", i18nSchema" // src/content/config.ts import { defineCollection } from 'astro:content'; import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; export const collections = { docs: defineCollection({ schema: docsSchema() }), - i18n: defineCollection({ type: 'data', schema: i18nSchema() }), + + i18n: defineCollection({ type: 'data', schema: i18nSchema() }), }; ``` diff --git a/docs/src/content/docs/guides/sidebar.mdx b/docs/src/content/docs/guides/sidebar.mdx index 02571ad23ae..a0035fa18cb 100644 --- a/docs/src/content/docs/guides/sidebar.mdx +++ b/docs/src/content/docs/guides/sidebar.mdx @@ -59,7 +59,8 @@ By combining links and groups, you can create a wide variety of sidebar layouts. Add a link to an internal or external page using an object with `label` and `link` properties. -```js +```js "label:" "link:" +// astro.config.mjs starlight({ sidebar: [ // A link to the CSS & Styling guide. @@ -88,7 +89,8 @@ Add a group using an object with `label` and `items` properties. The `label` will be used as the heading for the group. Add links or subgroups to the `items` array. -```js +```js /(label:) 'G/ /(label:) 'St/ "items:" +// astro.config.mjs starlight({ sidebar: [ // A group of links labelled "Guides". @@ -142,7 +144,8 @@ Pages will be sorted alphabetically by filename by default. Add an autogenerated group using an object with `label` and `autogenerate` properties. Your `autogenerate` configuration must specify the `directory` to use for sidebar entries. For example, with the following configuration: -```js +```js "label:" "autogenerate:" +// astro.config.mjs starlight({ sidebar: [ { @@ -195,8 +198,9 @@ Use the [`sidebar` frontmatter field](/reference/frontmatter/#sidebar) in indivi Sidebar frontmatter options allow you to set a [custom label](/reference/frontmatter/#label) or add a [badge](/reference/frontmatter/#badge) to a link, [hide](/reference/frontmatter/#hidden) a link from the sidebar, or define a [custom sort weighting](/reference/frontmatter/#order). -```md +```md "sidebar:" --- +# src/content/docs/example.md title: My page sidebar: # Set a custom label for the link @@ -237,7 +241,8 @@ The `sidebar` frontmatter configuration is only used for autogenerated links and Links, groups, and autogenerated groups can also include a `badge` property to display a badge next to their label. -```js +```js {11,18} +// astro.config.mjs starlight({ sidebar: [ { @@ -303,7 +308,8 @@ Customize the badge styling using an object with `text` and `variant` properties The `text` represents the content to display (e.g. "New"). Override the `default` styling, which uses the accent color of your site, by setting the `variant` property to one of the following values: `note`, `tip`, `danger`, `caution` or `success`. -```js +```js {11} +// astro.config.mjs starlight({ sidebar: [ { @@ -344,7 +350,8 @@ Links can also include an `attrs` property to add custom HTML attributes to the In the following example, `attrs` is used to add a `target="_blank"` attribute, so that the link opens in a new tab, and to apply a custom `style` attribute to italicize the link label: -```js +```js {11} +// astro.config.mjs starlight({ sidebar: [ { @@ -387,7 +394,8 @@ The configuration above generates the following sidebar: Use the `translations` property on link and group entries to translate the link or group label for each supported language by specifying a [BCP-47](https://www.w3.org/International/questions/qa-choosing-language-tags) language tag, e.g. `"en"`, `"ar"`, or `"zh-CN"`, as the key and the translated label as the value. The `label` property will be used for the default locale and for languages without a translation. -```js +```js {6-8,12-14,19-21} +// astro.config.mjs starlight({ sidebar: [ { @@ -434,7 +442,8 @@ Browsing the documentation in Brazilian Portuguese will generate the following s Groups of links can be collapsed by default by setting the `collapsed` property to `true`. -```js +```js {6-7} +// astro.config.mjs starlight({ sidebar: [ { @@ -467,7 +476,8 @@ The configuration above generates the following sidebar: [Autogenerated groups](#autogenerated-groups) respect the `collapsed` value of their parent group: -```js +```js {6-7} +// astro.config.mjs starlight({ sidebar: [ { @@ -504,7 +514,8 @@ The configuration above generates the following sidebar: This behavior can be overridden by defining the `autogenerate.collapsed` property. -```js +```js {6-8} "collapsed: true" +// astro.config.mjs starlight({ sidebar: [ { diff --git a/docs/src/content/docs/manual-setup.mdx b/docs/src/content/docs/manual-setup.mdx index bff4b01e825..720ea8f7186 100644 --- a/docs/src/content/docs/manual-setup.mdx +++ b/docs/src/content/docs/manual-setup.mdx @@ -44,7 +44,7 @@ The Starlight integration is configured in your `astro.config.mjs` file. Add a `title` to get started: -```js {7-9} +```js ins="'My delightful docs site'" // astro.config.mjs import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx index 9f27bf36bd2..f700762c7e3 100644 --- a/docs/src/content/docs/reference/configuration.mdx +++ b/docs/src/content/docs/reference/configuration.mdx @@ -42,6 +42,7 @@ Set the description for your website. Used in metadata shared with search engine Set a logo image to show in the navigation bar alongside or instead of the site title. You can either set a single `src` property or set separate image sources for `light` and `dark`. ```js +// astro.config.mjs starlight({ logo: { src: './src/assets/my-logo.svg', @@ -72,6 +73,7 @@ Configure the table of contents shown on the right of each page. By default, `` of your Starlight site. Can be useful for adding analytics and other third-party scripts and resources. ```js +// astro.config.mjs starlight({ head: [ // Example: add Fathom analytics script tag. @@ -471,6 +482,7 @@ A page can override this setting or the link text and/or URL using the [`prev`]( Set the path of the default favicon for your website which should be located in the `public/` directory and be a valid (`.ico`, `.gif`, `.jpg`, `.png`, or `.svg`) icon file. ```js +// astro.config.mjs starlight({ favicon: '/images/favicon.svg', }), @@ -479,6 +491,7 @@ starlight({ If you need to set additional variants or fallback favicons, you can add tags using the [`head` option](#head): ```js +// astro.config.mjs starlight({ favicon: '/images/favicon.svg'. head: [ @@ -512,6 +525,7 @@ For example, this page is titled “Configuration Reference” and this site is Provide the paths to components to override Starlight’s default implementations. ```js +// astro.config.mjs starlight({ components: { SocialLinks: './src/components/MySocialLinks.astro', diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md index e1adddb5a3c..487b6a297a0 100644 --- a/docs/src/content/docs/reference/frontmatter.md +++ b/docs/src/content/docs/reference/frontmatter.md @@ -5,8 +5,9 @@ description: An overview of the default frontmatter fields Starlight supports. You can customize individual Markdown and MDX pages in Starlight by setting values in their frontmatter. For example, a regular page might set `title` and `description` fields: -```md +```md {3-4} --- +# src/content/docs/example.md title: About this project description: Learn more about the project I’m working on. --- @@ -42,6 +43,7 @@ You can add additional tags to your page’s `` using the `head` frontmatt ```md --- +# src/content/docs/example.md title: About us head: # Use a custom tag @@ -59,6 +61,7 @@ Customize the heading levels to be included or set to `false` to hide the table ```md --- +# src/content/docs/example.md title: Page with only H2s in the table of contents tableOfContents: minHeadingLevel: 2 @@ -68,6 +71,7 @@ tableOfContents: ```md --- +# src/content/docs/example.md title: Page with no table of contents tableOfContents: false --- @@ -92,6 +96,7 @@ For example, this config shows some common options, including loading an image f ```md --- +# src/content/docs/example.md title: My Home Page template: splash hero: @@ -115,6 +120,7 @@ You can display different versions of the hero image in light and dark modes. ```md --- +# src/content/docs/example.md hero: image: alt: A glittering, brightly colored logo @@ -169,6 +175,7 @@ For example, this page displays a banner including a link to `example.com`. ```md --- +# src/content/docs/example.md title: Page with a banner banner: content: | @@ -185,6 +192,7 @@ Overrides the [global `lastUpdated` option](/reference/configuration/#lastupdate ```md --- +# src/content/docs/example.md title: Page with a custom last update date lastUpdated: 2022-08-09 --- @@ -198,6 +206,7 @@ Overrides the [global `pagination` option](/reference/configuration/#pagination) ```md --- +# src/content/docs/example.md # Hide the previous page link prev: false --- @@ -205,6 +214,7 @@ prev: false ```md --- +# src/content/docs/example.md # Override the previous page link text prev: Continue the tutorial --- @@ -212,6 +222,7 @@ prev: Continue the tutorial ```md --- +# src/content/docs/example.md # Override both the previous page link and text prev: link: /unrelated-page/ @@ -227,6 +238,7 @@ Same as [`prev`](#prev) but for the next page link. ```md --- +# src/content/docs/example.md # Hide the next page link next: false --- @@ -241,6 +253,7 @@ Set whether this page should be included in the [Pagefind](https://pagefind.app/ ```md --- +# src/content/docs/example.md # Hide this page from the search index pagefind: false --- @@ -273,6 +286,7 @@ Set the label for this page in the sidebar when displayed in an autogenerated gr ```md --- +# src/content/docs/example.md title: About this project sidebar: label: About @@ -288,6 +302,7 @@ Lower numbers are displayed higher up in the link group. ```md --- +# src/content/docs/example.md title: Page to display first sidebar: order: 1 @@ -303,6 +318,7 @@ Prevents this page from being included in an autogenerated sidebar group. ```md --- +# src/content/docs/example.md title: Page to hide from autogenerated sidebar sidebar: hidden: true @@ -319,6 +335,7 @@ Optionally, pass a [`BadgeConfig` object](/reference/configuration/#badgeconfig) ```md --- +# src/content/docs/example.md title: Page with a badge sidebar: # Uses the default variant matching your site’s accent color @@ -328,6 +345,7 @@ sidebar: ```md --- +# src/content/docs/example.md title: Page with a badge sidebar: badge: @@ -344,6 +362,7 @@ HTML attributes to add to the page link in the sidebar when displayed in an auto ```md --- +# src/content/docs/example.md title: Page opening in a new tab sidebar: # Opens the page in a new tab diff --git a/docs/src/content/docs/reference/overrides.md b/docs/src/content/docs/reference/overrides.md index a9938ad7f0d..387e485d11c 100644 --- a/docs/src/content/docs/reference/overrides.md +++ b/docs/src/content/docs/reference/overrides.md @@ -18,6 +18,7 @@ To type your custom components, import the `Props` type from Starlight: ```astro --- +// src/components/Custom.astro import type { Props } from '@astrojs/starlight/props'; const { hasSidebar } = Astro.props; From 8c0e85c9ab43d9dcdfc424d306d715504d67528a Mon Sep 17 00:00:00 2001 From: HiDeoo <494699+HiDeoo@users.noreply.github.com> Date: Tue, 21 Nov 2023 00:40:16 +0100 Subject: [PATCH 2/7] docs: update sidebar guide links group ec regexp Co-authored-by: Hippo <6137925+hippotastic@users.noreply.github.com> --- docs/src/content/docs/guides/sidebar.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/guides/sidebar.mdx b/docs/src/content/docs/guides/sidebar.mdx index a0035fa18cb..12b4c980739 100644 --- a/docs/src/content/docs/guides/sidebar.mdx +++ b/docs/src/content/docs/guides/sidebar.mdx @@ -89,7 +89,7 @@ Add a group using an object with `label` and `items` properties. The `label` will be used as the heading for the group. Add links or subgroups to the `items` array. -```js /(label:) 'G/ /(label:) 'St/ "items:" +```js /^\s*(label:|items:)/ // astro.config.mjs starlight({ sidebar: [ From 483a775c4dd3a618623bcf6392938636f5ecfede Mon Sep 17 00:00:00 2001 From: HiDeoo <494699+HiDeoo@users.noreply.github.com> Date: Wed, 22 Nov 2023 11:25:44 +0100 Subject: [PATCH 3/7] docs: apply chris suggestions Co-authored-by: Chris Swithinbank <swithinbank@gmail.com> --- docs/src/content/docs/guides/components.mdx | 16 ++++++++++------ docs/src/content/docs/guides/customization.mdx | 4 ++-- docs/src/content/docs/manual-setup.mdx | 2 +- 3 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx index a86d5ffe326..e89fce3a180 100644 --- a/docs/src/content/docs/guides/components.mdx +++ b/docs/src/content/docs/guides/components.mdx @@ -16,7 +16,7 @@ These look like HTML tags but start with an uppercase letter matching the name i ```mdx --- -# src/content/docs/index.mdx +# src/content/docs/example.mdx title: Welcome to my docs --- @@ -38,7 +38,7 @@ Learn more about [using components in MDX](https://docs.astro.build/en/guides/ma Starlight applies default styling to your Markdown content, for example adding margin between elements. If these styles conflict with your component’s appearance, set the `not-content` class on your component to disable them. -```astro +```astro 'class="not-content"' --- // src/components/Example.astro --- @@ -61,7 +61,8 @@ You can display a tabbed interface using the `<Tabs>` and `<TabItem>` components Each `<TabItem>` must have a `label` to display to users. ```mdx -# src/content/docs/index.mdx +# src/content/docs/example.mdx + import { Tabs, TabItem } from '@astrojs/starlight/components'; <Tabs> @@ -87,7 +88,8 @@ Wrap multiple cards in the `<CardGrid>` component to display cards side-by-side A `<Card>` requires a `title` and can optionally include an `icon` attribute set to the name of [one of Starlight’s built-in icons](#all-icons). ```mdx -# src/content/docs/index.mdx +# src/content/docs/example.mdx + import { Card, CardGrid } from '@astrojs/starlight/components'; <Card title="Check this out">Interesting content you want to highlight.</Card> @@ -136,7 +138,8 @@ A `<LinkCard>` requires a `title` and an [`href`](https://developer.mozilla.org/ Group multiple `<LinkCard>` components in `<CardGrid>` to display cards side-by-side when there’s enough space. ```mdx -# src/content/docs/index.mdx +# src/content/docs/example.mdx + import { LinkCard, CardGrid } from '@astrojs/starlight/components'; <LinkCard @@ -176,7 +179,8 @@ Starlight provides a set of common icons that you can display in your content us Each `<Icon>` requires a [`name`](#all-icons) and can optionally include a `label`, `size`, and `color` attribute. ```mdx -# src/content/docs/index.mdx +# src/content/docs/example.mdx + import { Icon } from '@astrojs/starlight/components'; <Icon name="star" color="goldenrod" size="2rem" /> diff --git a/docs/src/content/docs/guides/customization.mdx b/docs/src/content/docs/guides/customization.mdx index 89f75bfb249..2a9af1ce801 100644 --- a/docs/src/content/docs/guides/customization.mdx +++ b/docs/src/content/docs/guides/customization.mdx @@ -147,7 +147,7 @@ tableOfContents: defineConfig({ integrations: [ starlight({ - title: '', + title: 'Docs with custom table of contents config', tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 }, }), ], @@ -409,7 +409,7 @@ It provides npm modules you can install for the fonts you want to use and includ To apply the font you set up to your site, use your chosen font’s name in a [custom CSS file](/guides/css-and-tailwind/#custom-css-styles). For example, to override Starlight’s default font everywhere, set the `--sl-font` custom property: -```css {4} +```css /* src/styles/custom.css */ :root { diff --git a/docs/src/content/docs/manual-setup.mdx b/docs/src/content/docs/manual-setup.mdx index 720ea8f7186..eb83d10ef06 100644 --- a/docs/src/content/docs/manual-setup.mdx +++ b/docs/src/content/docs/manual-setup.mdx @@ -44,7 +44,7 @@ The Starlight integration is configured in your `astro.config.mjs` file. Add a `title` to get started: -```js ins="'My delightful docs site'" +```js ins={8} // astro.config.mjs import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; From 65b5fa6338a3e168437c36dc958a0dcfa3448bc0 Mon Sep 17 00:00:00 2001 From: HiDeoo <494699+HiDeoo@users.noreply.github.com> Date: Wed, 22 Nov 2023 11:29:13 +0100 Subject: [PATCH 4/7] docs: apply kevin suggestion Co-authored-by: Kevin Zuniga Cuellar <46791833+kevinzunigacuellar@users.noreply.github.com> --- docs/src/content/docs/guides/i18n.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/guides/i18n.mdx b/docs/src/content/docs/guides/i18n.mdx index 1c9ae47782c..ac5b48065d4 100644 --- a/docs/src/content/docs/guides/i18n.mdx +++ b/docs/src/content/docs/guides/i18n.mdx @@ -152,7 +152,7 @@ You can provide translations for additional languages you support — or overrid 1. Configure the `i18n` data collection in `src/content/config.ts` if it isn’t configured already: - ```diff lang="js" ins=", i18nSchema" + ```diff lang="js" ins=/, (i18nSchema)/ // src/content/config.ts import { defineCollection } from 'astro:content'; import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; From f961f5612137245199354bc9f6392b84776426ba Mon Sep 17 00:00:00 2001 From: HiDeoo <494699+HiDeoo@users.noreply.github.com> Date: Wed, 22 Nov 2023 17:52:12 +0100 Subject: [PATCH 5/7] docs: remove new frame titles from customization.mdx --- docs/src/content/docs/guides/customization.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/src/content/docs/guides/customization.mdx b/docs/src/content/docs/guides/customization.mdx index 2a9af1ce801..598396325b1 100644 --- a/docs/src/content/docs/guides/customization.mdx +++ b/docs/src/content/docs/guides/customization.mdx @@ -48,8 +48,7 @@ By default, the logo will be displayed alongside your site’s `title`. If your logo image already includes the site title, you can visually hide the title text by setting the `replacesTitle` option. The `title` text will still be included for screen readers so that the header remains accessible. -```js {6} -// astro.config.mjs +```js {5} starlight({ title: 'Docs With My Logo', logo: { @@ -79,7 +78,6 @@ You can display different versions of your logo in light and dark modes. 2. Add the path to your logo variants as the `light` and `dark` options instead of `src` in `astro.config.mjs`: ```diff lang="js" - // astro.config.mjs starlight({ title: 'Docs With My Logo', logo: { From dad6bdcab110034334e297e51e6e5053ecb28ff7 Mon Sep 17 00:00:00 2001 From: HiDeoo <494699+HiDeoo@users.noreply.github.com> Date: Wed, 22 Nov 2023 17:57:50 +0100 Subject: [PATCH 6/7] docs: remove new frame titles from configuration.mdx --- .../content/docs/reference/configuration.mdx | 25 ++++--------------- 1 file changed, 5 insertions(+), 20 deletions(-) diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx index f700762c7e3..4808adb1365 100644 --- a/docs/src/content/docs/reference/configuration.mdx +++ b/docs/src/content/docs/reference/configuration.mdx @@ -42,7 +42,6 @@ Set the description for your website. Used in metadata shared with search engine Set a logo image to show in the navigation bar alongside or instead of the site title. You can either set a single `src` property or set separate image sources for `light` and `dark`. ```js -// astro.config.mjs starlight({ logo: { src: './src/assets/my-logo.svg', @@ -73,7 +72,6 @@ Configure the table of contents shown on the right of each page. By default, `<h Enable “Edit this page” links by setting the base URL these should use. The final link will be `editLink.baseUrl` + the current page path. For example, to enable editing pages in the `withastro/starlight` repo on GitHub: ```js -// astro.config.mjs starlight({ editLink: { baseUrl: 'https://github.com/withastro/starlight/edit/main/', @@ -99,7 +97,6 @@ Each item must have a `label` and one of the following properties: - `autogenerate` — an object specifying a directory of your docs to automatically generate a group of links from. ```js -// astro.config.mjs starlight({ sidebar: [ // A single link item labelled “Home”. @@ -132,8 +129,7 @@ Groups of links are expanded by default. You can change this behavior by setting Autogenerated subgroups respect the `collapsed` property of their parent group by default. Set the `autogenerate.collapsed` property to override this. -```js {6,17} -// astro.config.mjs +```js {5,16} sidebar: [ // A collapsed group of links. { @@ -159,8 +155,7 @@ sidebar: [ If your site is multilingual, each item’s `label` is considered to be in the default locale. You can set a `translations` property to provide labels for your other supported languages: -```js {6,10,15} -// astro.config.mjs +```js {5,9,14} sidebar: [ // An example sidebar with labels translated to Brazilian Portuguese. { @@ -220,7 +215,6 @@ interface BadgeConfig { Each entry should use the directory where that language’s files are saved as the key. ```js -// astro.config.mjs import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; @@ -285,8 +279,7 @@ The writing direction of this language; `"ltr"` for left-to-right (the default) You can serve the default language without a `/lang/` directory by setting a `root` locale: -```js {4-7} -// astro.config.mjs +```js {3-6} starlight({ locales: { root: { @@ -321,7 +314,6 @@ import SocialLinksType from '../../../components/social-links-type.astro'; Optional details about the social media accounts for this site. Adding any of these will display them as icon links in the site header. ```js -// astro.config.mjs starlight({ social: { codeberg: 'https://codeberg.org/knut/examples', @@ -348,7 +340,6 @@ Provide CSS files to customize the look and feel of your Starlight site. Supports local CSS files relative to the root of your project, e.g. `'./src/custom.css'`, and CSS you installed as an npm module, e.g. `'@fontsource/roboto'`. ```js -// astro.config.mjs starlight({ customCss: ['./src/custom-styles.css', '@fontsource/roboto'], }); @@ -365,8 +356,7 @@ See the [“Code blocks” guide](/guides/authoring-content/#code-blocks) to lea You can use any of the standard [Expressive Code configuration options](https://github.com/expressive-code/expressive-code/blob/main/packages/astro-expressive-code/README.md#configuration) as well as some Starlight-specific properties, by setting them in Starlight’s `expressiveCode` option. For example, set Expressive Code’s `styleOverrides` option to override the default CSS. This enables customizations like giving your code blocks rounded corners: -```js ins={3-5} -// astro.config.mjs +```js ins={2-4} starlight({ expressiveCode: { styleOverrides: { borderRadius: '0.5rem' }, @@ -376,8 +366,7 @@ starlight({ If you want to disable Expressive Code, set `expressiveCode: false` in your Starlight config: -```js ins={3} -// astro.config.mjs +```js ins={2} starlight({ expressiveCode: false, }); @@ -430,7 +419,6 @@ Add custom tags to the `<head>` of your Starlight site. Can be useful for adding analytics and other third-party scripts and resources. ```js -// astro.config.mjs starlight({ head: [ // Example: add Fathom analytics script tag. @@ -482,7 +470,6 @@ A page can override this setting or the link text and/or URL using the [`prev`]( Set the path of the default favicon for your website which should be located in the `public/` directory and be a valid (`.ico`, `.gif`, `.jpg`, `.png`, or `.svg`) icon file. ```js -// astro.config.mjs starlight({ favicon: '/images/favicon.svg', }), @@ -491,7 +478,6 @@ starlight({ If you need to set additional variants or fallback favicons, you can add tags using the [`head` option](#head): ```js -// astro.config.mjs starlight({ favicon: '/images/favicon.svg'. head: [ @@ -525,7 +511,6 @@ For example, this page is titled “Configuration Reference” and this site is Provide the paths to components to override Starlight’s default implementations. ```js -// astro.config.mjs starlight({ components: { SocialLinks: './src/components/MySocialLinks.astro', From f07fea6bab364582eed18c771018d495a37ad46e Mon Sep 17 00:00:00 2001 From: HiDeoo <494699+HiDeoo@users.noreply.github.com> Date: Wed, 22 Nov 2023 18:02:20 +0100 Subject: [PATCH 7/7] docs: remove new frame titles from sidebar.mdx --- docs/src/content/docs/guides/sidebar.mdx | 24 +++++++----------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/docs/src/content/docs/guides/sidebar.mdx b/docs/src/content/docs/guides/sidebar.mdx index 12b4c980739..c6247fe9f8e 100644 --- a/docs/src/content/docs/guides/sidebar.mdx +++ b/docs/src/content/docs/guides/sidebar.mdx @@ -60,7 +60,6 @@ By combining links and groups, you can create a wide variety of sidebar layouts. Add a link to an internal or external page using an object with `label` and `link` properties. ```js "label:" "link:" -// astro.config.mjs starlight({ sidebar: [ // A link to the CSS & Styling guide. @@ -90,7 +89,6 @@ The `label` will be used as the heading for the group. Add links or subgroups to the `items` array. ```js /^\s*(label:|items:)/ -// astro.config.mjs starlight({ sidebar: [ // A group of links labelled "Guides". @@ -145,7 +143,6 @@ Pages will be sorted alphabetically by filename by default. Add an autogenerated group using an object with `label` and `autogenerate` properties. Your `autogenerate` configuration must specify the `directory` to use for sidebar entries. For example, with the following configuration: ```js "label:" "autogenerate:" -// astro.config.mjs starlight({ sidebar: [ { @@ -241,8 +238,7 @@ The `sidebar` frontmatter configuration is only used for autogenerated links and Links, groups, and autogenerated groups can also include a `badge` property to display a badge next to their label. -```js {11,18} -// astro.config.mjs +```js {10,17} starlight({ sidebar: [ { @@ -308,8 +304,7 @@ Customize the badge styling using an object with `text` and `variant` properties The `text` represents the content to display (e.g. "New"). Override the `default` styling, which uses the accent color of your site, by setting the `variant` property to one of the following values: `note`, `tip`, `danger`, `caution` or `success`. -```js {11} -// astro.config.mjs +```js {10} starlight({ sidebar: [ { @@ -350,8 +345,7 @@ Links can also include an `attrs` property to add custom HTML attributes to the In the following example, `attrs` is used to add a `target="_blank"` attribute, so that the link opens in a new tab, and to apply a custom `style` attribute to italicize the link label: -```js {11} -// astro.config.mjs +```js {10} starlight({ sidebar: [ { @@ -394,8 +388,7 @@ The configuration above generates the following sidebar: Use the `translations` property on link and group entries to translate the link or group label for each supported language by specifying a [BCP-47](https://www.w3.org/International/questions/qa-choosing-language-tags) language tag, e.g. `"en"`, `"ar"`, or `"zh-CN"`, as the key and the translated label as the value. The `label` property will be used for the default locale and for languages without a translation. -```js {6-8,12-14,19-21} -// astro.config.mjs +```js {5-7,11-13,18-20} starlight({ sidebar: [ { @@ -442,8 +435,7 @@ Browsing the documentation in Brazilian Portuguese will generate the following s Groups of links can be collapsed by default by setting the `collapsed` property to `true`. -```js {6-7} -// astro.config.mjs +```js {5-6} starlight({ sidebar: [ { @@ -476,8 +468,7 @@ The configuration above generates the following sidebar: [Autogenerated groups](#autogenerated-groups) respect the `collapsed` value of their parent group: -```js {6-7} -// astro.config.mjs +```js {5-6} starlight({ sidebar: [ { @@ -514,8 +505,7 @@ The configuration above generates the following sidebar: This behavior can be overridden by defining the `autogenerate.collapsed` property. -```js {6-8} "collapsed: true" -// astro.config.mjs +```js {5-7} "collapsed: true" starlight({ sidebar: [ {