play: add docs example with Aside and Since ported

examples/with-markdoc/src/components/Aside.astro

@@ -0,0 +1,123 @@
+---
+export interface Props {
+	type?: 'note' | 'tip' | 'caution' | 'danger';
+	title?: string;
+}
+
+const t = {
+	'aside.tip': 'Tip',
+};
+const { type = 'note', title = t[`aside.${type}`] } = Astro.props as Props;
+
+// SVG icon paths based on GitHub Octicons
+const icons: Record<NonNullable<Props['type']>, { viewBox: string; d: string }> = {
+	note: {
+		viewBox: '0 0 18 18',
+		d: 'M0 3.75C0 2.784.784 2 1.75 2h12.5c.966 0 1.75.784 1.75 1.75v8.5A1.75 1.75 0 0114.25 14H1.75A1.75 1.75 0 010 12.25v-8.5zm1.75-.25a.25.25 0 00-.25.25v8.5c0 .138.112.25.25.25h12.5a.25.25 0 00.25-.25v-8.5a.25.25 0 00-.25-.25H1.75zM3.5 6.25a.75.75 0 01.75-.75h7a.75.75 0 010 1.5h-7a.75.75 0 01-.75-.75zm.75 2.25a.75.75 0 000 1.5h4a.75.75 0 000-1.5h-4z',
+	},
+	tip: {
+		viewBox: '0 0 18 18',
+		d: 'M14 0a8.8 8.8 0 0 0-6 2.6l-.5.4-.9 1H3.3a1.8 1.8 0 0 0-1.5.8L.1 7.6a.8.8 0 0 0 .4 1.1l3.1 1 .2.1 2.4 2.4.1.2 1 3a.8.8 0 0 0 1 .5l2.9-1.7a1.8 1.8 0 0 0 .8-1.5V9.5l1-1 .4-.4A8.8 8.8 0 0 0 16 2v-.1A1.8 1.8 0 0 0 14.2 0h-.1zm-3.5 10.6-.3.2L8 12.3l.5 1.8 2-1.2a.3.3 0 0 0 .1-.2v-2zM3.7 8.1l1.5-2.3.2-.3h-2a.3.3 0 0 0-.3.1l-1.2 2 1.8.5zm5.2-4.5a7.3 7.3 0 0 1 5.2-2.1h.1a.3.3 0 0 1 .3.3v.1a7.3 7.3 0 0 1-2.1 5.2l-.5.4a15.2 15.2 0 0 1-2.5 2L7.1 11 5 9l1.5-2.3a15.3 15.3 0 0 1 2-2.5l.4-.5zM12 5a1 1 0 1 1-2 0 1 1 0 0 1 2 0zm-8.4 9.6a1.5 1.5 0 1 0-2.2-2.2 7 7 0 0 0-1.1 3 .2.2 0 0 0 .3.3c.6 0 2.2-.4 3-1.1z',
+	},
+	caution: {
+		viewBox: '-1 1 18 18',
+		d: 'M8.9 1.5C8.7 1.2 8.4 1 8 1s-.7.2-.9.5l-7 12a1 1 0 0 0 0 1c.2.3.6.5 1 .5H15c.4 0 .7-.2.9-.5a1 1 0 0 0 0-1l-7-12zM9 13H7v-2h2v2zm0-3H7V6h2v4z',
+	},
+	danger: {
+		viewBox: '0 1 14 17',
+		d: 'M5 .3c.9 2.2.5 3.4-.5 4.3C3.5 5.6 2 6.5 1 8c-1.5 2-1.7 6.5 3.5 7.7-2.2-1.2-2.6-4.5-.3-6.6-.6 2 .6 3.3 2 2.8 1.4-.4 2.3.6 2.2 1.7 0 .8-.3 1.4-1 1.8A5.6 5.6 0 0 0 12 10c0-2.9-2.5-3.3-1.3-5.7-1.5.2-2 1.2-1.8 2.8 0 1-1 1.8-2 1.3-.6-.4-.6-1.2 0-1.8C8.2 5.3 8.7 2.5 5 .3z',
+	},
+};
+const { viewBox, d } = icons[type];
+---
+
+<aside class={`content ${type}`} aria-label={title}>
+	<p class="title" aria-hidden="true">
+		<span class="icon">
+			<svg xmlns="http://www.w3.org/2000/svg" viewBox={viewBox} width={16} height={16}>
+				<path fill-rule="evenodd" d={d}></path>
+			</svg>
+		</span>
+		{title}
+	</p>
+	<section>
+		<slot />
+	</section>
+</aside>
+
+<style>
+	aside {
+		--color-base-purple: 269, 79%;
+		--color-base-teal: 180, 80%;
+		--aside-color-base: var(--color-base-purple);
+		--aside-color-lightness: 54%;
+		--aside-accent-color: hsl(var(--aside-color-base), var(--aside-color-lightness));
+		--aside-text-lightness: 20%;
+		--aside-text-accent-color: hsl(var(--aside-color-base), var(--aside-text-lightness));
+
+		border-inline-start: 4px solid var(--aside-accent-color);
+		padding: 1rem;
+		background-color: hsla(
+			var(--aside-color-base),
+			var(--aside-color-lightness),
+			var(--theme-accent-opacity)
+		);
+		/* Indicates the aside boundaries for forced colors users, transparent is changed to a solid color */
+		outline: 1px solid transparent;
+	}
+
+	:global(.theme-dark) aside {
+		--aside-text-lightness: 85%;
+	}
+
+	.title {
+		line-height: 1;
+		margin-bottom: 0.5rem;
+		font-size: 0.9rem;
+		letter-spacing: 0.05em;
+		font-weight: bold;
+		text-transform: uppercase;
+		color: var(--aside-text-accent-color);
+	}
+
+	.icon svg {
+		width: 1.5em;
+		height: 1.5em;
+		vertical-align: middle;
+		fill: currentcolor;
+	}
+
+	aside :global(a),
+	aside :global(a > code:not([class*='language'])) {
+		color: var(--aside-text-accent-color);
+	}
+
+	aside :global(p),
+	aside.content :global(ul) {
+		color: var(--theme-text);
+	}
+
+	:global(.theme-dark) aside :global(code:not([class*='language'])) {
+		color: var(--theme-code-text);
+	}
+
+	aside :global(pre) {
+		margin-left: 0;
+		margin-right: 0;
+	}
+
+	.tip {
+		--aside-color-lightness: 42%;
+		--aside-color-base: var(--color-base-teal);
+	}
+
+	.caution {
+		--aside-color-lightness: 59%;
+		--aside-color-base: var(--color-base-yellow);
+	}
+
+	.danger {
+		--aside-color-lightness: 54%;
+		--aside-color-base: var(--color-base-red);
+	}
+</style>

examples/with-markdoc/src/components/Badge.astro

@@ -0,0 +1,34 @@
+---
+export interface Props {
+	variant?: 'neutral' | 'accent';
+}
+const { variant = 'neutral' } = Astro.props as Props;
+---
+
+<span class={`badge ${variant}`}><slot /></span>
+
+<style>
+	.badge {
+		display: inline-block;
+		font-size: 0.75rem;
+		border: 1px solid;
+		line-height: 1;
+		padding: 0.25em 0.5em;
+		font-weight: bold;
+		text-transform: uppercase;
+		letter-spacing: 0.1ch;
+		white-space: nowrap;
+	}
+
+	.neutral {
+		border-color: var(--theme-dim);
+		color: var(--theme-text-light);
+		background-color: var(--theme-dim-lighter);
+	}
+
+	.accent {
+		border-color: var(--theme-accent);
+		color: var(--theme-text-accent);
+		background-color: var(--theme-bg-accent);
+	}
+</style>

examples/with-markdoc/src/components/Since.astro

@@ -0,0 +1,46 @@
+---
+import Badge from './Badge.astro';
+
+export interface Props {
+	pkg?: string;
+	v: string;
+}
+
+const { v, pkg = 'astro' } = Astro.props as Props;
+
+/**
+ * Split a semantic version string like `0.23.3` into a tuple of `[major, minor, patch]`.
+ */
+const parseSemVer = (semver: string) =>
+	semver.split('.').map((part) => parseInt(part.replace(/[^0-9]/g, ''), 10));
+
+/**
+ * Decide a feature is “new” if it was added in the latest minor version.
+ * For example, `@version 0.24.0` will be new as long as `astro@latest` is 0.24.x
+ */
+const getFeatureStatus = async (sinceVersion: string): Promise<'beta' | 'new' | 'current'> => {
+	const astroInfo = await fetch(`https://registry.npmjs.org/${pkg}/latest`).then((res) =>
+		res.json()
+	);
+	const latestAstroVersion = astroInfo.version;
+	const [sinceMajor, sinceMinor] = parseSemVer(sinceVersion);
+	const [latestMajor, latestMinor] = parseSemVer(latestAstroVersion);
+	if (sinceMajor > latestMajor) {
+		return 'beta';
+	}
+	if (sinceMajor === latestMajor) {
+		if (sinceMinor > latestMinor) return 'beta';
+		if (sinceMinor === latestMinor) return 'new';
+	}
+	return 'current';
+};
+
+const featureStatus = await getFeatureStatus(v);
+---
+
+<span>
+	<strong>Added in</strong>
+	<code>{pkg}@{v}</code>
+	{featureStatus === 'new' && <Badge variant="accent">New</Badge>}
+	{featureStatus === 'beta' && <Badge variant="accent">Beta</Badge>}
+</span>

examples/with-markdoc/src/content/config.ts

@@ -0,0 +1,17 @@
+import { defineCollection, z } from 'astro:content';
+
+const blog = defineCollection({
+	schema: z.object({
+		title: z.string(),
+	}),
+});
+
+const docs = defineCollection({
+	schema: z.object({
+		title: z.string(),
+		description: z.string(),
+		i18nReady: z.boolean(),
+	}),
+});
+
+export const collections = { blog, docs };

examples/with-markdoc/src/content/docs/content-collections.mdoc

@@ -0,0 +1,43 @@
+---
+title: Content Collections
+description: >-
+  Content collections help organize your Markdown and type-check your
+  frontmatter with schemas.
+i18nReady: false
+---
+
+**Content collections** are the best way to work with Markdown and MDX in any Astro project. Content collections are a feature of Astro that help manage your content files in a project. Collections help to organize your content, validate your frontmatter, and provide automatic TypeScript type-safety for all of your content.
+
+## What are Content Collections?
+
+{% tabs client="load" /%}
+
+{% since v="2.0.0" /%}
+
+A **content collection** is any directory inside the reserved `src/content` project directory, such as `src/content/newsletter` and `src/content/blog`. Only content collections are allowed inside the `src/content` directory. This directory cannot be used for anything else.
+
+A **content entry** is any piece of content stored inside of your content collection directory. Content entries are stored as either Markdown (`.md`) or MDX (`.mdx`) files. You can use any filename you want, but we recommend using a consistent naming scheme (lower-case, dashes instead of spaces) to make it easier to find and organize your content.
+
+```sh
+- src/content/
+  - **newsletter/** the "newsletter" collection
+    - week-1.md a collection entry
+    - week-2.md a collection entry
+    - week-3.md a collection entry
+```
+
+Once you have a collection, you can start [querying your content](#querying-collections) using Astro's built-in content APIs.
+
+### The .astro Directory
+
+Astro stores important metadata for content collections in an `.astro` directory in your project. No action is needed on your part to maintain or update this directory. You are encouraged to ignore it entirely while working in your project.
+
+The `.astro` directory will be updated for you automatically anytime you run the [`astro dev`](/en/reference/cli-reference/#astro-dev), [`astro build`](/en/reference/cli-reference/#astro-build) commands. You can run [`astro sync`](/en/reference/cli-reference/#astro-sync) at any time to update the `.astro` directory manually.
+
+{% aside type="tip" %}
+If you're using Git for version control, we recommend ignoring the `.astro` directory by adding `.astro` to your `.gitignore`. This tells Git to ignore this directory and any files inside of it.
+
+```bash
+echo "\n.astro" >> .gitignore
+```
+{% /aside %}