[reorg] new Recipes section; Basics streamlined (#2550)

* initial sidebar reorg

* tutorials key

* new (hidden) recipes page

* move ui frameworks back to guides

* add astro syntax hidden page

* update recipes page

* create initial nanostores recipe page from sharing state

* Update pages for content collections

* falso -> false

* new captcha recipe pulled from endpoints

* add yaml support recipe

* move some component content out

* slimmed down components page

* some simplifying/editing edits to routing

* update links to astro-syntax

* attempt CI fail fixes

* nav.ts indentation?

* update CLI page and put in Learn menu

* more edits to CLI page intro for friendliness

* update i18n nav.ts for sidebar updates

* final nav.ts cleanup

* more user-friendly CLI intro

* even friendlier CLI!

* hack so CLI is in Learn category for sidebar highlighting

* some Components page tidying - slots!

* minor tidying of Astro syntax as a standalone page

* Highlight recipes when on a page in recipes folder

* Recipe components

* i18n(ja): Update nav.ts (#2693)

* move Routing and MD/MDX pages into guides

* rename new page Astro Template Syntax

* recipes folder

* Move fonts back to guides

* all recipes -> more recipes

* remove back button on recipe index

* Fix nav key type issue

* Move main recipes file to avoid `index.mdx`

* i18n(zh-cn): Update nav.ts based on reorg-incl-recipes (#2687)

* i18n(zh-cn): Update nav.ts

* i18n(zh-cn): Update nav.ts

* Update nav.ts

---------

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

* update of nav (#2725)

* kill nanostores, replace with orig sharing state

* add commented out original content back in to CLI

* Make logos optional in `<CardsNav>`

* Add optional `description` support to `<CardsNav>`

* Configure content collection schema for recipes (no tags yet)

* Add `type: recipe` to recipes & write missing descriptions

* Very basic `<RecipesNav>` — needs tag, i18n support & styling

* Replace `<RecipeBox>` with `<RecipesNav>`

* Fix es nav type error

* sharing state -> share state between islands

* Tweak card grid to work better for recipe cards

* Style description text in `<Card>`

* Remove unneeded styles in `<CMSGuidesNav>`

* Fix margins on `<RecipesNav>`

* Fix `<RecipesNav>` links & remove tags

* Add `<RecipeLayout>`

* move CLI Reference page back to reference, remove Learn cateogry

* add links back to recipes from original pages

* nit edits in integrations-guide

* links no longer notes; use emoji

* related recipes bold text instead of heading; might delete

* updated links to recipes - one line

* fix broken link, move recipe to proper page!

* Curated -> Official

* [i18nIgnore] Add new subpage handling logic (#2758)

* [i18nIgnore] Add new subpage handling logic

* Revert "[i18nIgnore] Add new subpage handling logic"

This reverts commit 5fce612.

* Refactor subpage highlighting logic

* Add missing frontmatter fields from translations

* Avoid using `import.meta.url`

---------

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

* handle forms recipe + skeleton

* build forms with api routes - 3 steps, examples for 5 frameworks

* captcha we -> you and formatting

* incorporate changes from PR2404 into Astro Syntax

* incorporated changes from 2404 into Astro Components

* update code example to show an Astro component vs UI framework

* prereqs

* yaml -> vite or rollup

* Sarah edits to HTML forms - check carefully for still needs!

* tiny Sarah edits

* Dan's improved instructions

Co-authored-by: Dan Jutan <danjutan@gmail.com>

* no typos under Yan's watch!

Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>

* removing inelegance!

Co-authored-by: Dan Jutan <danjutan@gmail.com>

* Update src/content/docs/en/recipes/build-forms.mdx

Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>

* Delete clipboard-check.svg

* Remove duplicate nav entry

* tweak order of guides

* nod to script and style tags in components, removed dup from script page

* remove forms recipes

* Update PT-BR `nav.ts` file

* nav tweaks esp routing

* bye bye, "sits the template"

* Use translations correct in `<RecipesNav>`

* Add `lang="en"` to English fallback content in `<RecipesNav>`

* Update PT-BR `rss.mdx` description

* Also update the PT-BR `title` prop!

---------

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
Co-authored-by: Shinya Fujino <shf0811@gmail.com>
Co-authored-by: Dan Jutan <danjutan@gmail.com>
Co-authored-by: 李瑞丰 <liruifeng1024@gmail.com>
Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com>
Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com>

src/components/CMSGuidesNav.astro

@@ -41,17 +41,4 @@ const links = enPages
 	.cms-nav > :global(*) {
 		margin-top: -2rem;
 	}
-
-	.cms-nav > :global(* + *) {
-		margin-top: -3rem;
-	}
-
-	.cms-nav :global(.scope) {
-		font-weight: normal;
-		color: var(--theme-text-lighter);
-	}
-
-	h3 {
-		margin-bottom: 0;
-	}
 </style>

src/components/LeftSidebar/LeftSidebar.astro

@@ -35,7 +35,7 @@ let activeTab: 'learn' | 'api' = 'learn';
 
 // Certain pages are not in the sidebar nav, so we manually set the active tab based on other factors (e.g. Algolia page category).
 const isReference = ['Error Reference', 'Reference'].includes(
-	getPageCategory(new URL(currentPage, import.meta.url))
+	getPageCategory({ pathname: currentPage })
 );
 if (isReference) {
 	activeTab = 'api';

src/components/LeftSidebar/SidebarContent.astro

@@ -1,5 +1,6 @@
 ---
-import { getLanguageFromURL, removeSubpageSegment } from '../../util';
+import { getLanguageFromURL } from '~/util';
+import { isSubPage } from '~/util/isSubPage';
 
 export interface Props {
 	type: TabType;
@@ -44,11 +45,7 @@ const lang = getLanguageFromURL(Astro.url.pathname);
 							<a
 								href={`${Astro.site?.pathname}${lang}/${slug}/`}
 								aria-current={`${currentPageMatch.endsWith(slug) ? 'page' : 'false'}`}
-								data-current-parent={`${
-									removeSubpageSegment(currentPageMatch).endsWith(removeSubpageSegment(slug))
-										? 'true'
-										: 'false'
-								}`}
+								data-current-parent={`${isSubPage(currentPageMatch, slug) ? 'true' : 'false'}`}
 							>
 								<Fragment set:html={text} /> {isFallback && <sup class="fallback">EN</sup>}
 							</a>

src/components/NavGrid/Card.astro

@@ -4,7 +4,7 @@ import BrandLogo from '../BrandLogo.astro';
 
 export interface Props {
 	href: string;
-	logo: LogoKey;
+	logo?: LogoKey;
 	current?: boolean;
 	minimal?: boolean;
 	[key: string]: any;
@@ -14,7 +14,7 @@ const { href, logo, current, minimal, class: classes, ...attrs } = Astro.props a
 ---
 
 <li class:list={['card', minimal ? 'card--minimal' : 'card--maximal', classes]} {...attrs}>
-	<BrandLogo brand={logo} />
+	{logo && <BrandLogo brand={logo} />}
 	<div class="stack">
 		<h3>
 			<a href={href} aria-current={current ? 'page' : 'false'}>

src/components/NavGrid/CardsNav.astro

@@ -8,10 +8,13 @@ export interface Props {
 	minimal?: boolean;
 	links: {
 		title: string;
+		description?: string;
 		href: string;
-		logo: LogoKey;
+		logo?: LogoKey;
 		/** Map of tag IDs to translated tag display text, e.g. `{ static: 'Statisch' }`. */
 		tags?: Record<string, string>;
+		/** The language of the content if it differs from the main page language. */
+		lang?: string;
 	}[];
 	class?: string;
 }
@@ -25,14 +28,15 @@ const currentPage = new URL(Astro.request.url).pathname;
 	<slot />
 	<Grid minimal={minimal}>
 		{
-			links.map(({ href, logo, title, tags }) => (
+			links.map(({ description, href, logo, title, tags, lang }) => (
 				<Card
-					{...{ minimal, logo, href }}
+					{...{ minimal, logo, href, lang }}
 					current={currentPage.includes(href)}
 					class={Object.keys(tags || {}).join(' ')}
 				>
 					<Fragment slot="title" set:html={title} />
 					<Fragment slot="details">
+						{description && <p class="description">{description}</p>}
 						{tags && (
 							<div class="tags">
 								{Object.values(tags).map((tag) => (
@@ -53,6 +57,12 @@ const currentPage = new URL(Astro.request.url).pathname;
 		accent-color: var(--theme-accent-secondary);
 	}
 
+	.description {
+		margin-top: 0.25rem;
+		color: var(--theme-text-lighter);
+		font-size: var(--theme-text-sm);
+	}
+
 	.tags {
 		display: flex;
 		gap: 0.5rem;

src/components/NavGrid/Grid.astro

@@ -18,19 +18,19 @@ const { minimal } = Astro.props as Props;
 		display: grid;
 		grid-template-columns: repeat(auto-fill, minmax(var(--column-min-width), 1fr));
 		grid-template-columns: repeat(auto-fill, minmax(min(var(--column-min-width), 100%), 1fr));
-		gap: 1.5rem;
+		gap: 2rem;
 		list-style: none;
+		align-items: start;
 	}
 
 	@media (min-width: 37.75em) {
 		.fluid-grid {
-			gap: 1.5rem 2.5rem;
+			gap: 2rem 2.5rem;
 		}
 	}
 
 	.fluid-grid--minimal {
 		--column-min-width: 6rem;
 		gap: 1.5rem 0.75rem;
-		align-items: start;
 	}
 </style>

src/components/RecipesNav.astro

@@ -0,0 +1,46 @@
+---
+import { recipePages } from '~/content';
+import { createIsLangEntry, isEnglishEntry } from '~/content/config';
+import { getLanguageFromURL, stripLangFromSlug } from '~/util';
+import CardsNav from './NavGrid/CardsNav.astro';
+
+export interface Props {
+	minimal?: boolean;
+}
+
+const lang = getLanguageFromURL(Astro.url.pathname);
+const langRecipes = recipePages.filter(createIsLangEntry(lang));
+const englishRecipes = recipePages.filter(isEnglishEntry);
+
+/** An array of all recipes, using translations if available and falling back to English otherwise. */
+const recipes = englishRecipes.map((fallback) => {
+	const slug = stripLangFromSlug(fallback.slug);
+	const translation = langRecipes.find((doc) => stripLangFromSlug(doc.slug) === slug);
+	return translation || fallback;
+});
+---
+
+<div>
+	<CardsNav
+		minimal={Astro.props.minimal}
+		links={recipes.map(({ data, slug }) => {
+			const linkLang = slug.split('/').shift();
+			return {
+				title: data.title,
+				description: data.description,
+				// Fallback entries will have a slug starting with 'en/',
+				// so we replace that to link to the correct language.
+				href: '/' + slug.replace('en/', `${lang}/`) + '/',
+				// Fallback content will be in English, unlike the page,
+				// so we set an explicit `lang="en"` for these entries.
+				lang: linkLang !== lang ? linkLang : undefined,
+			};
+		})}
+	/>
+</div>
+
+<style>
+	div > :global(*) {
+		margin-top: -2rem;
+	}
+</style>

src/content.ts

@@ -1,6 +1,7 @@
 import { getCollection } from 'astro:content';
-import { isEnglishEntry, isTutorialEntry } from './content/config';
+import { isEnglishEntry, isRecipeEntry, isTutorialEntry } from './content/config';
 
 export const allPages = await getCollection('docs');
 export const tutorialPages = allPages.filter(isTutorialEntry);
+export const recipePages = allPages.filter(isRecipeEntry);
 export const englishPages = allPages.filter(isEnglishEntry);

src/content/config.ts

@@ -45,6 +45,11 @@ export const tutorialSchema = baseSchema.extend({
 	unitTitle: z.string().optional(),
 });
 
+export const recipeSchema = baseSchema.extend({
+	type: z.literal('recipe'),
+	description: z.string(),
+});
+
 export type DeployEntry = CollectionEntry<'docs'> & {
 	data: z.infer<typeof deploySchema>;
 };
@@ -65,6 +70,10 @@ export type TutorialEntry = CollectionEntry<'docs'> & {
 	data: z.infer<typeof tutorialSchema>;
 };
 
+export type RecipeEntry = CollectionEntry<'docs'> & {
+	data: z.infer<typeof recipeSchema>;
+};
+
 export type IntegrationCategory = z.infer<typeof integrationSchema>['category'];
 
 export function isCmsEntry(entry: CollectionEntry<'docs'>): entry is CmsEntry {
@@ -83,10 +92,18 @@ export function isMigrationEntry(entry: CollectionEntry<'docs'>): entry is Migra
 	return entry.data.type === 'migration';
 }
 
-export function isEnglishEntry(entry: CollectionEntry<'docs'>): boolean {
-	return entry.slug.startsWith('en/');
+export function isRecipeEntry(entry: CollectionEntry<'docs'>): entry is RecipeEntry {
+	return entry.data.type === 'recipe';
 }
 
+export function createIsLangEntry(lang: string) {
+	return function isLangEntry(entry: CollectionEntry<'docs'>): boolean {
+		return entry.slug.startsWith(lang + '/');
+	};
+}
+
+export const isEnglishEntry = createIsLangEntry('en');
+
 const docs = defineCollection({
 	schema: z.union([
 		baseSchema,
@@ -95,6 +112,7 @@ const docs = defineCollection({
 		migrationSchema,
 		tutorialSchema,
 		deploySchema,
+		recipeSchema,
 	]),
 });