Add MDs for LLMs pattern

docusaurus.config.js

@@ -1,8 +1,7 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
 require("dotenv").config();
-const lightCodeTheme = require("prism-react-renderer/themes/github");
-const darkCodeTheme = require("prism-react-renderer/themes/dracula");
+const {themes} = require("prism-react-renderer");
 
 const theme = require("shiki/themes/nord.json");
 const { remarkCodeHike } = require("@code-hike/mdx");
@@ -27,8 +26,11 @@ const config = {
   organizationName: "Flow", // Usually your GitHub org/user name.
   projectName: "Cadence", // Usually your repo name.
 
-  onBrokenLinks: "throw",
-  onBrokenMarkdownLinks: "warn",
+  markdown: {
+    hooks: {
+      onBrokenMarkdownLinks: "warn",
+    },
+  },
 
   // Even if you don't use internalization, you can use this field to set useful
   // metadata like html lang. For example, if your site is Chinese, you may want
@@ -91,6 +93,15 @@ const config = {
 
   themes: [hasTypesense && "docusaurus-theme-search-typesense"].filter(Boolean),
 
+  plugins: [
+    [
+      require.resolve("./plugins/markdown-export"),
+      {
+        docsDir: undefined, // Will default to siteDir/docs
+      },
+    ],
+  ],
+
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
@@ -140,8 +151,8 @@ const config = {
         ],
       },
       prism: {
-        theme: lightCodeTheme,
-        darkTheme: darkCodeTheme,
+        theme: themes.github,
+        darkTheme: themes.dracula,
       },
       typesense: hasTypesense && {
         // Replace this with the name of your index/collection.

package.json

@@ -15,25 +15,24 @@
   },
   "dependencies": {
     "@code-hike/mdx": "^0.9.0",
-    "@docusaurus/core": "3.0.0",
-    "@docusaurus/preset-classic": "3.0.0",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/preset-classic": "3.9.2",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^1.2.1",
-    "docusaurus-theme-search-typesense": "^0.14.0",
+    "docusaurus-theme-search-typesense": "0.25.0",
     "dotenv": "^16.3.1",
-    "lottie-react": "^2.4.0",
+    "globby": "^11.1.0",
     "next": "^12.0.7",
-    "prism-react-renderer": "^1.3.5",
+    "prism-react-renderer": "2.4.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-icons": "^4.11.0",
     "react-syntax-highlighter": "^15.5.0",
-    "react-youtube": "^10.1.0",
     "shiki": "^0.14.5",
     "web-vitals": "^4.2.4"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.0.0",
+    "@docusaurus/module-type-aliases": "3.9.2",
     "autoprefixer": "^10.4.20",
     "postcss": "^8.4.49",
     "tailwindcss": "^3.4.17",

plugins/markdown-export/index.js

@@ -0,0 +1,98 @@
+const fs = require("fs");
+const path = require("path");
+const globby = require("globby");
+
+module.exports = function markdownExportPlugin(context, options = {}) {
+  const { siteDir, baseUrl } = context;
+  const docsDir = options.docsDir ?? path.join(siteDir, "docs");
+  const outDirRel = options.outDirRel ?? "md"; // build/md
+
+  async function copyTree(srcDir, outDir) {
+    if (!fs.existsSync(srcDir)) return;
+    const mdPaths = await globby(["**/*.md", "**/*.mdx"], { cwd: srcDir });
+    for (const rel of mdPaths) {
+      const src = path.join(srcDir, rel);
+      // Keep the original extension so MDX shortcodes remain intact
+      // If filename is index.md, remove it from the path
+      let dest = path.join(outDir, outDirRel, rel);
+      if (path.basename(rel) === "index.md" || path.basename(rel) === "index.mdx") {
+        const dir = path.dirname(rel);
+        const ext = path.extname(rel);
+        // Remove the index.md from the path: foo/bar/index.md -> foo/bar.md
+        dest = path.join(outDir, outDirRel, dir + ext);
+      }
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(src, dest);
+    }
+  }
+
+  return {
+    name: "markdown-export",
+    async postBuild({ outDir, routes }) {
+      // 1) Copy docs source to build/md
+      await copyTree(docsDir, outDir);
+
+      // 2) Emit a path map: HTML route -> Markdown URL (best effort)
+      const map = {};
+      for (const r of routes) {
+        const p = r.path; // e.g. /docs/intro
+        // naive mirror: /docs/foo -> /md/foo(.mdx|.md). We'll try .mdx first.
+        if (p.startsWith(baseUrl + "docs")) {
+          const rel = p.replace(baseUrl, "").replace(/^docs\/?/, "");
+          map[p] = `${baseUrl}${outDirRel}/${rel.replace(/\/$/, "")}.mdx`;
+        }
+      }
+      fs.mkdirSync(path.join(outDir, outDirRel), { recursive: true });
+      fs.writeFileSync(
+        path.join(outDir, outDirRel, "_index.json"),
+        JSON.stringify(map, null, 2)
+      );
+
+      // 3) Emit a well-known manifest for LLM crawlers
+      const llmsTxt =
+        Object.entries(map)
+          .map(([htmlUrl, mdUrl]) => `${htmlUrl} -> ${mdUrl}`)
+          .join("\n") + "\n";
+      const wellKnownDir = path.join(outDir, ".well-known");
+      fs.mkdirSync(wellKnownDir, { recursive: true });
+      fs.writeFileSync(path.join(wellKnownDir, "llms.txt"), llmsTxt);
+
+      // 4) Generate llms-full.txt - a single file with all markdown content
+      let fullContent = "# Cadence Language Documentation - Complete Documentation\n\n";
+      fullContent += "This file contains all documentation in Markdown format.\n\n";
+      fullContent += "---\n\n";
+
+      // Read and combine all markdown files
+      const mdFiles = await globby(["**/*.md", "**/*.mdx"], { 
+        cwd: path.join(outDir, outDirRel),
+        absolute: false
+      });
+
+      for (const mdFile of mdFiles.sort()) {
+        const fullPath = path.join(outDir, outDirRel, mdFile);
+        if (fs.existsSync(fullPath)) {
+          const content = fs.readFileSync(fullPath, "utf-8");
+          fullContent += `\n# File: /md/${mdFile}\n\n`;
+          fullContent += content;
+          fullContent += "\n\n---\n\n";
+        }
+      }
+
+      fs.writeFileSync(path.join(outDir, "llms-full.txt"), fullContent);
+
+      // 5) Copy llms.txt to build output
+      const llmsTxtPath = path.join(siteDir, "static", "llms.txt");
+      if (fs.existsSync(llmsTxtPath)) {
+        fs.copyFileSync(llmsTxtPath, path.join(outDir, "llms.txt"));
+      }
+    },
+    injectHtmlTags() {
+      return {
+        headTags: [
+          // Discovery hint that Markdown is available
+          { tagName: "meta", attributes: { name: "llm:available-format", content: "text/markdown" } },
+        ],
+      };
+    },
+  };
+};

src/pages/index.js

@@ -1,20 +1,13 @@
-import React from 'react';
+import React, { useEffect } from 'react';
 import clsx from 'clsx';
-import Head from 'next/head';
+import Head from '@docusaurus/Head';
 import Link from '@docusaurus/Link';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Layout from '@theme/Layout';
+import BrowserOnly from '@docusaurus/BrowserOnly';
 import HomepageFeatures from '@site/src/components/HomepageFeatures';
 import { FcLock, FcIdea, FcChargeBattery, FcMindMap } from 'react-icons/fc';
 import { HiArrowRight, HiArrowSmDown } from 'react-icons/hi';
-import { PrismAsyncLight as SyntaxHighlighter } from 'react-syntax-highlighter';
-import { tomorrow } from 'react-syntax-highlighter/dist/cjs/styles/prism';
-import Lottie from "lottie-react";
-import securityAnimation from "./security.json";
-import debuggingAnimation from "./debugging.json";
-import composabilityAnimation from "./composability.json";
-import powerAnimation from "./power.json";
-import learnAnimation from "./learn.json";
 
 import styles from './index.module.css';
 import Logo from '@site/static/img/logo.svg';
@@ -52,8 +45,6 @@ function cadence(Prism) {
 
 cadence.displayName = 'cadence'
 
-SyntaxHighlighter.registerLanguage('cadence', cadence)
-
 function HomepageHeader() {
   const {siteConfig} = useDocusaurusContext();
   return (
@@ -71,18 +62,19 @@ function HomepageHeader() {
 
 export default function Home() {
   const {siteConfig} = useDocusaurusContext();
+
   return (
     <Layout
       title={`Hello from ${siteConfig.title}`}
       description="Cadence is a resource-oriented programming language that introduces new features to smart contract programming that help developers ensure that their code is safe, secure, clear, and approachable.">
+      <Head>
+        <title>Cadence</title>
+      </Head>
       <main>
 
       <div className="content-wrapper">
           <div className="feature">
             <div>
-            <Head>
-              <title>Cadence</title>
-            </Head>
               <Logo title="Cadence" className="logo" width="18em" height="4em" />
               <h2>
                 Forge the future of decentralized apps.
@@ -98,12 +90,21 @@ export default function Home() {
             </div>
 
             <div style={{maxWidth: "30rem"}}>
-              <SyntaxHighlighter
-                className="code"
-                language="cadence"
-                style={tomorrow}
-                showLineNumbers={true}
-              >{example}</SyntaxHighlighter>
+              <BrowserOnly>
+                {() => {
+                  const { PrismAsyncLight: SyntaxHighlighter } = require('react-syntax-highlighter');
+                  const { tomorrow } = require('react-syntax-highlighter/dist/cjs/styles/prism');
+                  SyntaxHighlighter.registerLanguage('cadence', cadence);
+                  return (
+                    <SyntaxHighlighter
+                      className="code"
+                      language="cadence"
+                      style={tomorrow}
+                      showLineNumbers={true}
+                    >{example}</SyntaxHighlighter>
+                  );
+                }}
+              </BrowserOnly>
             </div>
           </div>
 
@@ -158,9 +159,7 @@ export default function Home() {
                   instead of preventing security footguns and attacks.
                 </p>
               </div>
-              <div>
-                <Lottie animationData={securityAnimation} />
-              </div>
+              <div />
             </div>
 
             <div className="feature alternate">
@@ -181,9 +180,7 @@ export default function Home() {
                   without requiring the original author of the type to plan or account for the intended behavior.
                 </p>
               </div>
-              <div>
-                <Lottie animationData={composabilityAnimation} />
-              </div>
+              <div />
             </div>
 
             <div className="feature">
@@ -196,9 +193,7 @@ export default function Home() {
                   and examples enable developers to start creating programs quickly and effectively.
                 </p>
               </div>
-              <div>
-              <Lottie animationData={learnAnimation} />
-              </div>
+              <div />
             </div>
 
             <div className="feature alternate">
@@ -215,9 +210,7 @@ export default function Home() {
                   or adding and sending funds with just one approval.
                 </p>
               </div>
-              <div>
-               <Lottie animationData={powerAnimation} />
-              </div>
+              <div />
             </div>
 
             <div className="feature">
@@ -234,9 +227,7 @@ export default function Home() {
                   unit & integration tests using Cadence.
                 </p>
               </div>
-              <div>
-                <Lottie animationData={debuggingAnimation} />
-              </div>
+              <div />
             </div>
 
           </div>

src/theme/AnnouncementBar/index.js

@@ -6,6 +6,10 @@ import AnnouncementBarContent from '@theme/AnnouncementBar/Content';
 import styles from './styles.module.css';
 export default function AnnouncementBar() {
   const {announcementBar} = useThemeConfig();
+  // If announcement bar is not configured, do not render and avoid using the hook
+  if (!announcementBar) {
+    return null;
+  }
   const {isActive, close} = useAnnouncementBar();
   if (!isActive) {
     return null;

src/theme/Layout/index.tsx

@@ -9,6 +9,13 @@ export default function LayoutWrapper(props: Props): JSX.Element {
   return (
     <>
       <Layout className="content-wrapper" {...props} />
+      {/* Hidden notice for LLM crawlers */}
+      <div style={{ display: 'none' }}>
+        <p>
+          Markdown versions of documentation are available. Add Accept: text/markdown header or ?format=md query parameter.
+          All documentation is also available at /llms-full.txt and individual files at /md/path/to/file.md
+        </p>
+      </div>
     </>
   );
 }