feat: added markdown alternate support

Author: gerardnico

apps/site/pages/components/open.md

@@ -0,0 +1,10 @@
+---
+title: Open Component
+---
+
+
+The `open` component is a component that permits to open:
+
+* alternate version of your pages such as [Markdown](../reference/ai.md#markdown-format-for-all-pages)
+* your page in an `agent`
+

apps/site/pages/reference/ai.md

@@ -0,0 +1,26 @@
+---
+title: AI Agent Support
+---
+
+## Markdown format for all pages
+
+All [pages](page.md) gets by default a Markdown version.
+
+The Markdown version can be asked:
+
+* by adding tne `md` at the end of the URL path
+* by setting the `accept` request header to `text/markdown`
+
+The elements that have the class `print:hidden` are not part of the output.
+
+Every HTML page announces this alternate version in a link head element:
+
+Example:
+
+```html
+<link rel="alternate" type="text/markdown" href="/index.md">
+```
+
+This alternate version is then used by the [Open Component](../components/open.md)
+
+The [static server generation](build.md#static-server-generation) generates also the Markdown version

apps/site/pages/reference/build.md

@@ -15,4 +15,10 @@ Example:
     "build": "interact favicon && interact build"
   }
 }
-```
+```
+
+## Static Server Generation
+
+On static server generation, an alternate markdown version
+is also generated for [AI agent consumption](ai.md#markdown-format-for-all-pages).
+

apps/site/pages/reference/markdown.md

@@ -18,7 +18,8 @@ We support the following 2 Markdown files type:
 They all share the common [Markdown syntax](markdown-syntax.md)
 
 Note that you can add support for more with [unified plugins](remark-rehype-unified.md).
-By [default](remark-rehype-unified.md#default), we apply the [Remark Gfm](https://github.com/remarkjs/remark-gfm) plugin to add
+By [default](remark-rehype-unified.md#default), we apply the [Remark Gfm](https://github.com/remarkjs/remark-gfm) plugin
+to add
 the [GitHub Syntax](https://github.github.com/gfm/)
 
 ### Custom components
@@ -34,3 +35,8 @@ They are recognized by the [2 Markdown file types](#file-types)
 You can change how Markdown is parsed with [remark and rehype plugins](remark-rehype-unified.md).
 
 The plugins are applied to all Markdown files.
+
+### AI Agent Support
+
+We also create Markdown version of every pages for consumption by [Ai Agent](ai.md#markdown-format-for-all-pages).
+

apps/site/pages/reference/remark-rehype-unified.md

@@ -71,4 +71,12 @@ To define the location of the configuration file, you can:
   the [root](directory-layout.md)
 * or set the value in the `markdown.configImportPath` of the [configuration file](conf.md). If the value starts with a
   `.`, it's considered a path from the [root directory](directory-layout.md) otherwise, it's considered a module name to
-  be searched from `nodes_modules`
+  be searched from `nodes_modules`
+
+## Usage
+
+They are used:
+
+* when reading [markdown page](markdown.md)
+* but also when writing [markdown page for agents](ai.md#markdown-format-for-all-pages)
+

src/interact/componentsProvider/contextProps.d.ts

@@ -1,13 +1,6 @@
 // don't use the relative path (not resolved)
 import type {FinalPage} from "../pages/interactPage.js";
 
-// Parsed request information used to route between RSC/SSR rendering.
-// Created by parseRenderRequest() from incoming HTTP requests.
-export type RscProps = {
-    isRsc: boolean // true if request should return RSC payload (via _.rsc suffix)
-    isAction: boolean // true if this is a server action call (POST request)
-    actionId?: string // server action ID from x-rsc-action header
-}
 
 /**
  * The context request props
@@ -20,7 +13,14 @@ export type ContextProps = {
     request: Request, // the original request
     // the routing normalized URL (with _.rsc suffix removed, no base, rewrite url, host may be fake)
     url: URL
-    rsc: RscProps
+    // derived information
+    meta: {
+        isRsc: boolean // true if request should return RSC payload (via _.rsc suffix)
+        isRscAction: boolean // true if this is a server action call (POST request)
+        rscActionId?: string // server action ID from x-rsc-action header
+        isMarkdown: boolean // true if this is a Markdown request
+        lastModified?: string; // last time modified (iso string)
+    } & Record<string, string | boolean | undefined>
     response: {
         status?: number
         headers?: HeadersInit;

src/interact/config/configSchema.ts

@@ -308,8 +308,7 @@ const Header = BaseComponentSchema.extend({
 
 const ComponentsConfigSetSchema = z.object({
     Header: Header.optional(),
-    Toc: TocSchema.optional(),
-    NotFound: BaseComponentSchema.optional(),
+    Toc: TocSchema.optional()
 }).catchall(BaseComponentSchema); // unknown keys fall back to base schema
 
 
@@ -321,6 +320,8 @@ const handlerConfigSchema = z.object({
 
 const MiddlewaresSchema = z.object({
     pipeline: z.array(handlerConfigSchema).describe("A list of middlewares").default([]),
+    // 404 is the default for GitHub
+    // https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site
     notFoundPath: z.string().describe("The page returned if no middleware answers the request").default("/404"),
 }).describe("Middleware Properties");
 

src/interact/markdown/plugins/rehype-remove-no-print.ts

@@ -0,0 +1,24 @@
+import {visit, SKIP} from 'unist-util-visit';
+import type {Root} from "hast";
+
+
+/**
+ * Unified rehype plugin that removes elements with the class "print:hidden"
+ */
+export default function rehypeRemoveNoPrint() {
+    return (tree: Root) => {
+        visit(tree, 'element', (node, index, parent) => {
+            if (!parent || index == null) return;
+
+            const classes = node.properties?.["className"];
+            const hasNoPrint = Array.isArray(classes)
+                ? classes.includes('print:hidden')
+                : typeof classes === 'string' && classes.split(' ').includes('print:hidden');
+
+            if (hasNoPrint) {
+                parent.children.splice(index, 1);
+                return [SKIP, index]; // don't descend, and re-check current index
+            }
+        });
+    };
+}

src/interact/pages/interactPage.d.ts

@@ -31,21 +31,13 @@ export type Frontmatter = {
     lang?: string;
 } & Record<string, string | undefined>
 
-/**
- * Derived meta
- */
-export type Derived = {
-    // iso string
-    lastModified?: string;
-} & Record<string, string | undefined>
 
 /**
  * The page meta
  */
 export type PageMeta<F = unknown, D = unknow> = {
     frontmatter?: F & Frontmatter;
     toc?: TocNode[];
-    derived?: D & Derived
 };
 
 /**

src/interact/tsconfig.json

@@ -2,7 +2,10 @@
   "extends": "../../tsconfig.json",
   "compilerOptions": {
     "moduleResolution": "NodeNext",
-    "module": "NodeNext"
+    "module": "NodeNext",
+    // needed because ssg uses the type of the generated entry.rsc.tsx
+    // not needed otherwise it will check go into the resources directory
+    // "jsx": "react-jsx"
   },
   "include": [
     "**/*",