docs: point readers (and their LLMs) at the markdown renditions (#2427)

Author: felixweinberger

docs/.vitepress/config.mts

@@ -53,6 +53,17 @@ export default defineConfig({
     buildEnd(siteConfig) {
         generateLlmsArtifacts(docsDir, siteConfig.outDir, siteUrl);
     },
+    transformPageData(pageData) {
+        // Every guide page has a markdown rendition next to its HTML (llms.ts);
+        // advertise it to tools via a rel=alternate link. The API reference has none.
+        if (!pageData.relativePath.startsWith('api/')) {
+            pageData.frontmatter.head ??= [];
+            pageData.frontmatter.head.push([
+                'link',
+                { rel: 'alternate', type: 'text/markdown', href: `${siteUrl}/${pageData.relativePath}` }
+            ]);
+        }
+    },
     themeConfig: {
         nav: [
             { text: 'Get started', link: '/get-started/first-server', activeMatch: '^/get-started/' },

docs/.vitepress/theme/MarkdownSource.vue

@@ -0,0 +1,17 @@
+<script setup lang="ts">
+import { useData, withBase } from 'vitepress';
+import { computed } from 'vue';
+
+// Every guide page has a markdown rendition generated next to its HTML (see
+// ../llms.ts); the generated API reference does not.
+const { page } = useData();
+const mdPath = computed(() => (page.value.relativePath.startsWith('api/') ? undefined : withBase(`/${page.value.relativePath}`)));
+</script>
+
+<template>
+    <div v-if="mdPath" class="markdown-source">
+        Are you an LLM (or feeding one)? This page as
+        <a :href="mdPath" target="_self">markdown</a> · <a :href="withBase('/llms.txt')" target="_self">llms.txt</a> ·
+        <a :href="withBase('/llms-full.txt')" target="_self">llms-full.txt</a>
+    </div>
+</template>

docs/.vitepress/theme/custom.css

@@ -171,3 +171,20 @@
     text-decoration: underline;
     margin-left: 4px;
 }
+
+/* --------------------------------------------------- markdown-source footer */
+
+.markdown-source {
+    margin-bottom: 16px;
+    padding-top: 16px;
+    border-top: 1px solid var(--vp-c-divider);
+    color: var(--vp-c-text-3);
+    font-size: 12px;
+    line-height: 1.5;
+}
+
+.markdown-source a {
+    color: var(--vp-c-text-2);
+    text-decoration: underline;
+    font-weight: 400;
+}

docs/.vitepress/theme/index.ts

@@ -3,13 +3,15 @@ import DefaultTheme from 'vitepress/theme';
 import { h } from 'vue';
 
 import Banner from './Banner.vue';
+import MarkdownSource from './MarkdownSource.vue';
 import './custom.css';
 
 export default {
     extends: DefaultTheme,
     Layout() {
         return h(DefaultTheme.Layout, null, {
-            'layout-top': () => h(Banner)
+            'layout-top': () => h(Banner),
+            'doc-footer-before': () => h(MarkdownSource)
         });
     }
 } satisfies Theme;