5.0.0 beta docs

.github/labeler.yml

@@ -7,8 +7,6 @@
 # so to match files in multiple different paths, we also need multiple "any" arrays.
 i18n:
 - any: ['src/content/docs/**/*.mdx', '!src/content/docs/en/**/*']
-- any: ['src/i18n/**/*', '!src/i18n/en/*']
-glossary:
-- any: ['src/content/docs/**/glossary.mdx']
-- any: ['contributor-guides/glossary.md']
-- any: ['contributor-guides/glossary.mdx']
+- any: ['src/content/i18n/*', '!src/content/i18n/en.yml']
+- any: ['src/content/nav/*', '!src/content/nav/en.ts']
+- any: ['i18n-guides/*']

.vscode/settings.json

@@ -9,5 +9,8 @@
   },
   "[typescript]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[mdx]": {
+    "files.trimTrailingWhitespace": false,
   }
 }

CONTRIBUTING.md

@@ -144,7 +144,7 @@ You can install and run the project locally using [pnpm](https://pnpm.io/). Head
 ```shell
 pnpm install
 
-pnpm start
+pnpm run dev
 ```
 
 If you’re copying these instructions, remember to [configure this project as a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork).

astro.config.ts

@@ -1,16 +1,15 @@
 import starlight from '@astrojs/starlight';
 import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections';
 import { defineConfig, sharpImageService } from 'astro/config';
-import { makeLocalesConfig } from './config/locales';
-import { makeSidebar } from './config/sidebar';
-
 import rehypeSlug from 'rehype-slug';
 import remarkSmartypants from 'remark-smartypants';
-
-import { sitemap } from './integrations/sitemap';
-import { starlightPluginAutolinkHeadings } from './plugins/rehype-autolink';
-import { rehypeTasklistEnhancer } from './plugins/rehype-tasklist-enhancer';
-import { remarkFallbackLang } from './plugins/remark-fallback-lang';
+import { sidebar } from './astro.sidebar';
+import { devServerFileWatcher } from './config/integrations/dev-server-file-watcher';
+import { sitemap } from './config/integrations/sitemap';
+import { makeLocalesConfig } from './config/locales';
+import { starlightPluginAutolinkHeadings } from './config/plugins/rehype-autolink';
+import { rehypeTasklistEnhancer } from './config/plugins/rehype-tasklist-enhancer';
+import { remarkFallbackLang } from './config/plugins/remark-fallback-lang';
 
 /* https://docs.netlify.com/configure-builds/environment-variables/#read-only-variables */
 const NETLIFY_PREVIEW_SITE = process.env.CONTEXT !== 'production' && process.env.DEPLOY_PRIME_URL;
@@ -21,9 +20,13 @@ const site = NETLIFY_PREVIEW_SITE || 'https://docs.astro.build/';
 export default defineConfig({
 	site,
 	integrations: [
+		devServerFileWatcher([
+			'./config/*', // Custom plugins and integrations
+			'./astro.sidebar.ts', // Sidebar configuration file
+			'./src/content/nav/*.ts', // Sidebar labels
+		]),
 		starlight({
 			title: 'Docs',
-			customCss: ['./src/styles/custom.css'],
 			expressiveCode: {
 				plugins: [pluginCollapsibleSections()],
 			},
@@ -38,22 +41,22 @@ export default defineConfig({
 				Pagination: './src/components/starlight/Pagination.astro',
 				Footer: './src/components/starlight/Footer.astro',
 				SiteTitle: './src/components/starlight/SiteTitle.astro',
-				Search: './src/components/starlight/Search.astro',
+				// Search: './src/components/starlight/Search.astro',
 				Sidebar: './src/components/starlight/Sidebar.astro',
 				MobileMenuFooter: './src/components/starlight/MobileMenuFooter.astro',
 				PageTitle: './src/components/starlight/PageTitle.astro',
 			},
 			editLink: {
-				baseUrl: 'https://github.com/withastro/docs/edit/main',
+				baseUrl: 'https://github.com/withastro/docs/edit/5.0.0-beta',
 			},
 			defaultLocale: 'en',
 			locales: makeLocalesConfig(),
-			sidebar: makeSidebar(),
+			sidebar,
 			social: {
 				github: 'https://github.com/withastro/astro',
 				discord: 'https://astro.build/chat',
 			},
-			pagefind: false,
+			// pagefind: false,
 			head: [
 				// Add ICO favicon fallback for Safari.
 				{

astro.sidebar.ts

@@ -0,0 +1,198 @@
+import type { StarlightUserConfig } from '@astrojs/starlight/types';
+import { group } from './config/sidebar';
+
+/**
+ * Starlight sidebar configuration object for the global site sidebar.
+ *
+ * - Top-level groups become tabs.
+ * - Use the `group()` utility function to define groups. This uses labels from our
+ *   `src/content/nav/*.ts` files instead of defining labels and translations inline.
+ *
+ */
+export const sidebar = [
+	// Start tab
+	group('start', {
+		items: [
+			'getting-started',
+			group('start.welcome', {
+				items: ['concepts/why-astro', 'concepts/islands', 'tutorial/0-introduction'],
+			}),
+			group('start.newProject', {
+				items: ['install-and-setup', 'basics/project-structure', 'develop-and-build',],
+			}),
+			group('start.config', {
+				items: [
+					'guides/configuring-astro',
+					'editor-setup',
+					'guides/typescript',
+					'guides/environment-variables',
+					'guides/dev-toolbar',
+				],
+			}),
+			group('start.migrate', {
+				collapsed: true,
+				autogenerate: { directory: 'guides/migrate-to-astro' },
+			}),
+		],
+	}),
+
+	// Guides tab
+	group('guides', {
+		items: [
+			group('guides.routing', {
+				items: [
+					'basics/astro-pages',
+					'guides/routing',
+					'guides/endpoints',
+					'guides/middleware',
+					'guides/internationalization',
+					'guides/prefetch',
+					'guides/view-transitions',
+				],
+			}),
+			group('guides.ui', {
+				items: [
+					'basics/astro-components',
+					'basics/layouts',
+					'guides/styling',
+					'guides/fonts',
+					'guides/syntax-highlighting',
+					'guides/client-side-scripts',
+					'guides/framework-components',
+				],
+			}),
+			group('guides.content', {
+				items: [
+					'guides/markdown-content',
+					'guides/content-collections',
+					'guides/images',
+					'guides/data-fetching',
+					'guides/astro-db',
+				],
+			}),
+			group('guides.serverRendering', {
+				items: ['guides/on-demand-rendering', 'guides/server-islands', 'guides/actions'],
+			}),
+			group('guides.upgrade', {
+				items: [
+					'upgrade-astro',
+					group('guides.upgrade.major', {
+						collapsed: true,
+						autogenerate: { directory: 'guides/upgrade-to' },
+					}),
+				],
+			}),
+			'guides/troubleshooting',
+			group('guides.recipes', { collapsed: true, autogenerate: { directory: 'recipes' } }),
+			'contribute',
+		],
+	}),
+
+	// Reference tab
+	group('reference', {
+		items: [
+			group('reference.syntax', {
+				items: ['reference/astro-syntax', 'reference/directives-reference'],
+			}),
+			'reference/configuration-reference',
+			'reference/cli-reference',
+			'guides/imports',
+			'reference/routing-reference',
+			group('reference.runtime', {
+				items: [
+					'reference/api-reference',
+					'reference/modules/astro-actions',
+					'reference/modules/astro-assets',
+					'reference/modules/astro-content',
+					'reference/modules/astro-env',
+					'reference/modules/astro-i18n',
+					'reference/modules/astro-middleware',
+					'reference/modules/astro-transitions',
+				],
+			}),
+			group('reference.other', {
+				items: [
+					'reference/integrations-reference',
+					'reference/adapter-reference',
+					'reference/content-loader-reference',
+					'reference/image-service-reference',
+					'reference/dev-toolbar-app-reference',
+					'reference/container-reference',
+					'reference/programmatic-reference',
+				],
+			}),
+			group('reference.experimental', {
+				items: [
+					'reference/experimental-flags',
+					'reference/experimental-flags/responsive-images',
+					'reference/experimental-flags/svg',
+					'reference/experimental-flags/client-prerender',
+					'reference/experimental-flags/content-intellisense',
+				],
+			}),
+			'reference/legacy-flags',
+			'reference/error-reference',
+		],
+	}),
+
+	// Integrations tab
+	group('integrations', {
+		items: [
+			'guides/integrations-guide',
+			group('integrations.ui', {
+				items: [
+					'guides/integrations-guide/alpinejs',
+					'guides/integrations-guide/preact',
+					'guides/integrations-guide/react',
+					'guides/integrations-guide/solid-js',
+					'guides/integrations-guide/svelte',
+					'guides/integrations-guide/vue',
+				],
+			}),
+			group('integrations.adapters', {
+				items: [
+					'guides/integrations-guide/cloudflare',
+					'guides/integrations-guide/netlify',
+					'guides/integrations-guide/node',
+					'guides/integrations-guide/vercel',
+				],
+			}),
+			group('integrations.other', {
+				items: [
+					'guides/integrations-guide/db',
+					'guides/integrations-guide/markdoc',
+					'guides/integrations-guide/mdx',
+					'guides/integrations-guide/partytown',
+					'guides/integrations-guide/sitemap',
+					'guides/integrations-guide/tailwind',
+				],
+			}),
+			'reference/publish-to-npm',
+		],
+	}),
+
+	// Third-party services tab
+	group('thirdParty', {
+		items: [
+			group('thirdParty.deployment', {
+				collapsed: true,
+				autogenerate: { directory: 'guides/deploy' },
+			}),
+			group('thirdParty.cms', {
+				collapsed: true,
+				autogenerate: { directory: 'guides/cms' },
+			}),
+			group('thirdParty.backend', {
+				collapsed: true,
+				autogenerate: { directory: 'guides/backend' },
+			}),
+			group('thirdParty.media', {
+				collapsed: true,
+				autogenerate: { directory: 'guides/media' },
+			}),
+			'guides/ecommerce',
+			'guides/authentication',
+			'guides/testing',
+		],
+	}),
+] satisfies StarlightUserConfig['sidebar'];

config/README.md

@@ -0,0 +1,5 @@
+# `config/`
+
+This directory contains code related to configuring the docs site, which is used in [`astro.config.ts`](../astro.config.ts).
+
+Primarily these are custom Astro integrations (in [`integrations/`](./integrations/)) and plugins for remark, rehype, or Starlight (in [`plugins/`](./plugins/)). Other utilities to simplify configuring the site are also included here.

config/integrations/dev-server-file-watcher.ts

@@ -0,0 +1,31 @@
+import type { AstroIntegration } from 'astro';
+import glob from 'fast-glob';
+
+/**
+ * Astro integration that registers the passed paths so that saving them triggers a dev server
+ * restart.
+ *
+ * It also supports passing glob patterns to watch a set of files matching a specific pattern.
+ *
+ * @param paths Array of file paths relative to the project root.
+ *
+ * @example
+ * // astro.config.mjs
+ * export default {
+ *   integrations: [
+ *     devServerFileWatcher(["./example.js", "./src/content/demo/*.yml"]),
+ *   ],
+ * }
+ */
+export const devServerFileWatcher = (paths: string[]) =>
+	({
+		name: 'dev-server-file-watcher',
+		hooks: {
+			async 'astro:config:setup'({ addWatchFile, config }) {
+				for (const path of paths) {
+					const files = await glob(path);
+					files.forEach((file) => addWatchFile(new URL(file, config.root)));
+				}
+			},
+		},
+	}) satisfies AstroIntegration;