Add more EC text markers and frames to Starlight docs (#1102)

Co-authored-by: Hippo <[email protected]> Co-authored-by: Chris Swithinbank <[email protected]> Co-authored-by: Kevin Zuniga Cuellar <[email protected]>
withastro · Nov 23, 2023 · 4b3143b · 4b3143b
1 parent 0c25c1f
commit 4b3143b
Show file tree

Hide file tree

Showing 9 changed files with 79 additions and 50 deletions.
diff --git 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,6 +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/example.mdx
+
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 
 <Tabs>
@@ -86,6 +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/example.mdx
+
 import { Card, CardGrid } from '@astrojs/starlight/components';
 
 <Card title="Check this out">Interesting content you want to highlight.</Card>
@@ -134,6 +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/example.mdx
+
 import { LinkCard, CardGrid } from '@astrojs/starlight/components';
 
 <LinkCard
@@ -173,6 +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/example.mdx
+
 import { Icon } from '@astrojs/starlight/components';
 
 <Icon name="star" color="goldenrod" size="2rem" />

diff --git 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
@@ -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,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
+```js {5}
 starlight({
   title: 'Docs With My Logo',
   logo: {
@@ -77,12 +77,12 @@ 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"
    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 +91,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 +107,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 +126,7 @@ By default, `<h2>` and `<h3>` headings are included in the table of contents. Ch
 <Tabs>
   <TabItem label="Frontmatter">
 
-```md
+```md {4-6}
 ---
 # src/content/docs/example.md
 title: Page with only H2s in the table of contents
@@ -139,13 +139,13 @@ tableOfContents:
   </TabItem>
   <TabItem label="Global config">
 
-```js
+```js {7}
 // astro.config.mjs
 
 defineConfig({
 	integrations: [
 		starlight({
-			title: '',
+			title: 'Docs with custom table of contents config',
 			tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
 		}),
 	],
@@ -160,7 +160,7 @@ Disable the table of contents entirely by setting the `tableOfContents` option t
 <Tabs>
   <TabItem label="Frontmatter">
 
-```md
+```md {4}
 ---
 # src/content/docs/example.md
 title: Page without a table of contents
@@ -171,7 +171,7 @@ tableOfContents: false
   </TabItem>
   <TabItem label="Global config">
 
-```js
+```js {7}
 // astro.config.mjs
 
 defineConfig({
@@ -194,7 +194,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 +230,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 +265,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 +322,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 +332,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 +381,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 +391,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',
     			],
     		}),
     	],

diff --git 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
@@ -59,7 +59,7 @@ 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:"
 starlight({
 	sidebar: [
 		// A link to the CSS & Styling guide.
@@ -88,7 +88,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
+```js /^\s*(label:|items:)/
 starlight({
 	sidebar: [
 		// A group of links labelled "Guides".
@@ -142,7 +142,7 @@ 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:"
 starlight({
 	sidebar: [
 		{
@@ -195,8 +195,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 +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
+```js {10,17}
 starlight({
 	sidebar: [
 		{
@@ -303,7 +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
+```js {10}
 starlight({
 	sidebar: [
 		{
@@ -344,7 +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
+```js {10}
 starlight({
 	sidebar: [
 		{
@@ -387,7 +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
+```js {5-7,11-13,18-20}
 starlight({
 	sidebar: [
 		{
@@ -434,7 +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
+```js {5-6}
 starlight({
 	sidebar: [
 		{
@@ -467,7 +468,7 @@ The configuration above generates the following sidebar:
 
 [Autogenerated groups](#autogenerated-groups) respect the `collapsed` value of their parent group:
 
-```js
+```js {5-6}
 starlight({
 	sidebar: [
 		{
@@ -504,7 +505,7 @@ The configuration above generates the following sidebar:
 
 This behavior can be overridden by defining the `autogenerate.collapsed` property.
 
-```js
+```js {5-7} "collapsed: true"
 starlight({
 	sidebar: [
 		{