Migrate Docs to Starlight (withastro#4266)

Co-authored-by: Genteure <[email protected]>
Co-authored-by: HiDeoo <[email protected]>
Co-authored-by: Sergio A. Arevalo Soria <[email protected]>
Co-authored-by: Atharva Pise <[email protected]>
Co-authored-by: Sarah Rainsberger <[email protected]>
Co-authored-by: Luiz Ferraz <[email protected]>
Co-authored-by: Mark Peck <[email protected]>
Co-authored-by: Vitor Ayres <[email protected]>
Co-authored-by: Lucid Jeon <[email protected]>
Co-authored-by: Elian <[email protected]>
Co-authored-by: Yan Thomas <[email protected]>
Co-authored-by: Chris Swithinbank <[email protected]>
Co-authored-by: Kevin Zuniga Cuellar <[email protected]>
Co-authored-by: hippotastic <[email protected]>
Co-authored-by: Voxel <[email protected]>

@tracker-major:./src/content/docs/en/getting-started.mdx;

Author: TheOtterlord

.github/workflows/ci.yml

@@ -66,15 +66,3 @@ jobs:
 
       - name: Run Check
         run: pnpm run lint:linkcheck
-  unitTest:
-    name: Check for code issues with Vitest
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: Install Tools & Dependencies
-        uses: ./.github/actions/install
-
-      - name: Run Check
-        run: pnpm run test

.gitignore

@@ -35,3 +35,4 @@ sandbox.config.json
 
 # Cached requests
 .cache
+**/_fonts/brand/

.prettierrc

@@ -5,18 +5,13 @@
   "tabWidth": 2,
   "trailingComma": "es5",
   "useTabs": true,
+  "plugins": ["prettier-plugin-astro"],
   "overrides": [
     {
       "files": [".*", "*.json", "*.md", "*.mdx", "*.toml", "*.yml"],
       "options": {
         "useTabs": false
       }
-    },
-    {
-      "files": ["**/*.astro"],
-      "options": {
-        "parser": "astro"
-      }
     }
   ]
 }

.vscode/settings.json

@@ -1,34 +1,75 @@
-import mdx from '@astrojs/mdx';
-import preact from '@astrojs/preact';
-import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import { defineConfig, sharpImageService } from 'astro/config';
+import { makeLocalesConfig } from './config/locales';
+import { makeSidebar } from './config/sidebar';
 
-import AutoImport from 'astro-auto-import';
-import rehypeAutolinkHeadings from 'rehype-autolink-headings';
 import rehypeSlug from 'rehype-slug';
 import remarkSmartypants from 'remark-smartypants';
 
-import { asideAutoImport, astroAsides } from './integrations/astro-asides';
-import { astroDocsExpressiveCode } from './integrations/expressive-code';
-import { sitemap } from './integrations/sitemap';
-import { autolinkConfig } from './plugins/rehype-autolink-config';
-import { rehypei18nAutolinkHeadings } from './plugins/rehype-i18n-autolink-headings';
 import { rehypeOptimizeStatic } from './plugins/rehype-optimize-static';
 import { rehypeTasklistEnhancer } from './plugins/rehype-tasklist-enhancer';
 import { remarkFallbackLang } from './plugins/remark-fallback-lang';
+import { sitemap } from './integrations/sitemap';
+
+/* https://vercel.com/docs/projects/environment-variables/system-environment-variables#system-environment-variables */
+const VERCEL_PREVIEW_SITE =
+	process.env.VERCEL_ENV !== 'production' &&
+	process.env.VERCEL_URL &&
+	`https://${process.env.VERCEL_URL}`;
+
+const site = VERCEL_PREVIEW_SITE || 'https://docs.astro.build/';
 
 // https://astro.build/config
 export default defineConfig({
-	site: 'https://docs.astro.build/',
+	site,
 	integrations: [
-		AutoImport({
-			imports: [asideAutoImport],
+		starlight({
+			title: 'Docs',
+			customCss: ['./src/styles/custom.css'],
+			logo: {
+				light: './src/assets/astro-logo-light.svg',
+				dark: './src/assets/astro-logo-dark.svg',
+				alt: 'Astro',
+			},
+			components: {
+        EditLink: './src/components/starlight/EditLink.astro',
+				Head: './src/components/starlight/Head.astro',
+				Hero: './src/components/starlight/Hero.astro',
+				MarkdownContent: './src/components/starlight/MarkdownContent.astro',
+				MobileTableOfContents: './src/components/starlight/MobileTableOfContents.astro',
+				TableOfContents: './src/components/starlight/TableOfContents.astro',
+				PageSidebar: './src/components/starlight/PageSidebar.astro',
+				Pagination: './src/components/starlight/Pagination.astro',
+				SiteTitle: './src/components/starlight/SiteTitle.astro',
+				Search: './src/components/starlight/Search.astro',
+				Sidebar: './src/components/starlight/Sidebar.astro',
+			},
+			editLink: {
+				baseUrl: 'https://github.com/withastro/docs/edit/main',
+			},
+			defaultLocale: 'en',
+			locales: makeLocalesConfig(),
+			sidebar: makeSidebar(),
+			social: {
+				github: 'https://github.com/withastro/astro',
+				discord: 'https://astro.build/chat',
+			},
+			pagefind: false,
+			head: [
+				// Add ICO favicon fallback for Safari.
+				{
+					tag: 'link',
+					attrs: {
+						rel: 'icon',
+						href: '/favicon.ico',
+						sizes: '32x32',
+					},
+				},
+			],
 		}),
-		preact({ compat: true }),
 		sitemap(),
-		astroAsides(),
-		astroDocsExpressiveCode(),
-		mdx(),
 	],
+	trailingSlash: 'always',
 	scopedStyleStrategy: 'where',
 	compressHTML: false,
 	markdown: {
@@ -41,14 +82,14 @@ export default defineConfig({
 		],
 		rehypePlugins: [
 			rehypeSlug,
-			// This adds links to headings
-			[rehypeAutolinkHeadings, autolinkConfig],
 			// Tweak GFM task list syntax
 			rehypeTasklistEnhancer(),
-			// Translates the autolink headings anchors
-			rehypei18nAutolinkHeadings(),
 			// Collapse static parts of the hast to html
 			rehypeOptimizeStatic,
 		],
 	},
+	image: {
+		domains: ['avatars.githubusercontent.com'],
+		service: sharpImageService(),
+	},
 });

astro.config.ts

@@ -0,0 +1,14 @@
+import type starlight from '@astrojs/starlight';
+import { normalizeLangTag } from '../src/i18n/bcp-normalize';
+import languages, { rtlLanguages } from '../src/i18n/languages';
+
+type StarlightLocalesConfig = NonNullable<Parameters<typeof starlight>[0]['locales']>;
+
+export function makeLocalesConfig(): StarlightLocalesConfig {
+	return Object.fromEntries(
+		Object.entries(languages).map(([locale, label]) => [
+			locale,
+			{ label, lang: normalizeLangTag(locale), dir: rtlLanguages.has(locale) ? 'rtl' : 'ltr' },
+		])
+	);
+}

config/locales.ts

@@ -0,0 +1,44 @@
+import type starlight from '@astrojs/starlight';
+import { normalizeLangTag } from '../src/i18n/bcp-normalize';
+import type { NavDict } from '../src/i18n/translation-checkers';
+import { navTranslations } from '../src/i18n/util';
+
+/** For an item in our sidebar, get translations of its label. */
+function getTranslations(item: NavDict[number]): Record<string, string> | undefined {
+	return Object.fromEntries(
+		Object.entries(navTranslations)
+			.map(([lang, translations]) => {
+				const translation = translations.find((t) => t.key === item.key);
+				return [
+					normalizeLangTag(lang),
+					translation && translation.text !== item.text ? translation?.text : '',
+				] as const;
+			})
+			.filter(([, text]) => Boolean(text))
+	);
+}
+
+type StarlightSidebarConfig = NonNullable<Parameters<typeof starlight>[0]['sidebar']>;
+
+/** Generate a Starlight sidebar config object from our existing `nav.ts` files. */
+export function makeSidebar(): StarlightSidebarConfig {
+	return navTranslations.en.reduce((sidebar, item) => {
+		if ('header' in item) {
+			sidebar.push({
+				label: item.text,
+				translations: getTranslations(item),
+				items: [],
+			});
+		} else {
+			const group = sidebar.at(-1);
+			if (group && 'items' in group) {
+				group.items.push({
+					label: item.text,
+					link: item.slug,
+					translations: getTranslations(item),
+				});
+			}
+		}
+		return sidebar;
+	}, [] as StarlightSidebarConfig);
+}