Fix Markdown content negotiation

.rumdl.toml

@@ -12,4 +12,6 @@ disable = [
   "MD046",
   # for some reason required for tables
   "MD058",
+  # indentations in lists
+  "MD077",
 ]

astro.config.mjs

@@ -3,43 +3,48 @@ import mdx from "@astrojs/mdx";
 import react from "@astrojs/react";
 import sitemap from "@astrojs/sitemap";
 import tailwind from "@astrojs/tailwind";
+import { defineConfig } from "astro/config";
 import expressiveCode from "astro-expressive-code";
 import icon from "astro-icon";
-import { defineConfig } from "astro/config";
 import rehypeExternalLinks from "rehype-external-links";
 import remarkEmoji from "remark-emoji";
 import remarkHeadingId from "remark-heading-id";
 
+const port = 3000;
+const site = process.env.ENV === "production"
+  ? "https://zero-to-nix.com"
+  : process.env.DEPLOY_PRIME_URL ?? `http://localhost:${port}`;
+
 export default defineConfig({
-  integrations: [
-    alpinejs({
-      entrypoint: "./src/entrypoint",
-    }),
-    expressiveCode(),
-    icon(),
-    mdx({
-      //gfm: true,
-      remarkPlugins: [remarkEmoji, remarkHeadingId],
-    }),
-    sitemap(),
-    tailwind(),
-    react(),
-  ],
-  markdown: {
-    rehypePlugins: [
-      [
-        rehypeExternalLinks,
-        { rel: ["nofollow noopener noreferrer"], target: "_blank" },
-      ],
-    ],
-  },
-  prefetch: {
-    prefetchAll: true,
-    defaultStrategy: "hover",
-  },
-  server: {
-    open: true,
-    port: 3000,
-  },
-  site: "https://zero-to-nix.com",
+	integrations: [
+		alpinejs({
+			entrypoint: "./src/entrypoint",
+		}),
+		expressiveCode(),
+		icon(),
+		mdx({
+			//gfm: true,
+			remarkPlugins: [remarkEmoji, remarkHeadingId],
+		}),
+		sitemap(),
+		tailwind(),
+		react(),
+	],
+	markdown: {
+		rehypePlugins: [
+			[
+				rehypeExternalLinks,
+				{ rel: ["nofollow noopener noreferrer"], target: "_blank" },
+			],
+		],
+	},
+	prefetch: {
+		prefetchAll: true,
+		defaultStrategy: "hover",
+	},
+	server: {
+		open: true,
+		port,
+	},
+	site,
 });

netlify.toml

@@ -7,7 +7,7 @@ publish = "dist"
 # only want to run `npm ci`, which actually uses the `package-lock.json` lockfile.
 # Source: https://answers.netlify.com/t/how-can-i-use-npm-ci-instead-of-npm-install/12570/14
 NPM_FLAGS = "--version"
-NODE_VERSION = "24.13.0" # Keep this in step with `nix develop --command node --version`
+NODE_VERSION = "24.14.0" # Keep this in step with `nix develop --command node --version`
 
 [context.production]
 environment = { ENV = "production" }

package.json

@@ -41,8 +41,10 @@
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "rehype-external-links": "^3.0.0",
+    "remark": "^15.0.1",
     "remark-emoji": "^5.0.2",
     "remark-heading-id": "^1.0.1",
+    "strip-markdown": "^6.0.0",
     "typescript": "^5.9.3"
   },
   "devDependencies": {

src/components/Head.astro

@@ -1,5 +1,6 @@
 ---
 import { SEO } from "astro-seo";
+import { plainText } from "../lib/utils";
 import { site } from "../site";
 import Posthog from "./Posthog.astro";
 
@@ -8,14 +9,19 @@ type Props = {
   description?: string;
   tags?: string[];
   author?: string;
+  markdownNegotiation?: boolean;
 };
 
 const root = Astro.site!.toString();
 const canonical = new URL(Astro.url.pathname, root);
 
 const { title: siteTitle, description: siteDescription } = site;
 
-const { title, description, tags } = Astro.props;
+const { title, description, tags, markdownNegotiation = false } = Astro.props;
+
+const plainDescription = description
+  ? (await plainText(description)).trim()
+  : siteDescription;
 
 const image = `${root}favicon.png`;
 ---
@@ -51,7 +57,7 @@ const image = `${root}favicon.png`;
 <SEO
   charset="utf-8"
   title={title ?? siteTitle}
-  description={description ?? siteDescription}
+  description={plainDescription}
   {canonical}
   openGraph={{
     basic: {
@@ -64,10 +70,20 @@ const image = `${root}favicon.png`;
   twitter={{
     site: root,
     title: title ?? siteTitle,
-    description,
+    description: plainDescription,
     image,
     card: "summary",
   }}
+  extend={{
+    link: markdownNegotiation
+      ? [
+          {
+            rel: "alternate",
+            href: `${canonical.origin}${canonical.pathname.replace(/\/$/, "")}.md`,
+          },
+        ]
+      : [],
+  }}
 />
 
 <link

src/layouts/Layout.astro

@@ -10,19 +10,20 @@ import { site } from "../site";
 type Props = {
   title?: string;
   description?: string;
+  markdownNegotiation?: boolean;
 };
 
 const { defaultLanguage } = site;
 
-const { title, description } = Astro.props;
+const { title, description, markdownNegotiation = false } = Astro.props;
 ---
 
 <html
   x-data={`{ quickStart: $persist(true), drawer: false, banner: $persist(true), language: $persist("${defaultLanguage}") }`}
   class="h-screen"
 >
   <head>
-    <Head {title} {description} />
+    <Head {title} {description} {markdownNegotiation} />
   </head>
   <body
     class="flex min-h-full flex-col bg-white font-sans text-dark antialiased dark:bg-dark dark:text-white"

src/lib/utils.ts

@@ -1,4 +1,6 @@
 import { marked } from "marked";
+import { remark } from "remark";
+import strip from "strip-markdown";
 
 export const conceptPagePath = (slug: string): string => {
   return pagePath("concepts", slug);
@@ -12,6 +14,11 @@ export const startPagePath = (slug: string): string => {
   return pagePath("start", slug.substring(1));
 };
 
+export const plainText = async (md: string): Promise<string> => {
+  const file = await remark().use(strip).process(md);
+  return String(file).trim();
+};
+
 const pagePath = (collection: string, slug: string): string => {
   return `/${collection}/${slug}`;
 };

src/pages/concepts/[slug].astro

@@ -39,7 +39,7 @@ const relatedConceptPages: { title: string; href: string }[] = (
   });
 ---
 
-<Layout {title} description={snippet}>
+<Layout {title} description={snippet} markdownNegotiation>
   <HorizontalContainer>
     <Hero
       {title}

src/pages/start/[slug].astro

@@ -36,7 +36,7 @@ const { Content } = await page.render();
 const numQuickStartPages = (await getStartPagesByOrderParam()).length;
 ---
 
-<Layout {title}>
+<Layout {title} markdownNegotiation>
   <HorizontalContainer>
     <Hero
       {title}

src/pages/start/[slug].md.ts

@@ -5,12 +5,10 @@ export const prerender = true;
 
 type Props = { entry: CollectionEntry<"start"> };
 
-const stripExt = (id: string) => id.replace(/\.(md|mdx)$/i, "");
-
 export const getStaticPaths = (async () => {
   const entries = await getCollection("start");
   return entries.map((entry) => ({
-    params: { slug: stripExt(entry.id) },
+    params: { slug: entry.slug.substring(1) },
     props: { entry },
   }));
 }) satisfies GetStaticPaths;
@@ -19,7 +17,7 @@ export const GET: APIRoute<Props> = async ({ props, params }) => {
   let entry: CollectionEntry<"start"> | undefined = props?.entry;
   if (!entry && typeof params.slug === "string") {
     const all = await getCollection("start");
-    entry = all.find((e) => stripExt(e.id) === params.slug);
+    entry = all.find((e) => e.slug.substring(1) === params.slug);
   }
   if (!entry) {
     return new Response("Not Found", { status: 404 });