feat(llms): implement LLM-friendly documentation formats

- Add root /llms.txt following llmstxt.org spec pointing to .section.md files
- Convert Lambda@Edge markdown generator from ES6 to CommonJS for compatibility
- Add Lambda test payloads and improved error handling to deployment docs
- Fix format-selector rendering on landing pages
- Fix format-selector dropdown overflow issue
- Remove broken section-level llms.txt generation (1,114 files)
- Add S3 bucket configuration via config.json for Lambda@Edge
- Update .gitignore for Lambda deployment artifacts and TS build files

Lambda@Edge now generates .md files on-demand with:
- Evaluated Hugo shortcodes
- Proper YAML frontmatter with product metadata
- Clean markdown without UI elements
- Section aggregation (parent + children in single file)

Author: jstirnaman

.gitignore

@@ -38,6 +38,7 @@ tmp
 
 # TypeScript build output
 **/dist/
+**/dist-lambda/
 
 # User context files for AI assistant tools
 .context/*
@@ -49,3 +50,13 @@ tmp
 # Lambda deployment artifacts
 deploy/llm-markdown/lambda-edge/markdown-generator/*.zip
 deploy/llm-markdown/lambda-edge/markdown-generator/package-lock.json
+deploy/llm-markdown/lambda-edge/markdown-generator/.package-tmp/
+deploy/llm-markdown/lambda-edge/markdown-generator/yarn.lock
+deploy/llm-markdown/lambda-edge/markdown-generator/config.json
+
+# JavaScript/TypeScript build artifacts
+*.tsbuildinfo
+*.d.ts
+*.d.ts.map
+*.js.map
+.eslintcache

assets/styles/layouts/_landing.scss

@@ -2,7 +2,7 @@
   display: flex;
   flex-direction: row;
   position: relative;
-  overflow: hidden;
+  overflow: visible; // Changed from hidden to allow format-selector dropdown
   border-radius: $radius 0 0 $radius;
   min-height: 700px;
   @include gradient($landing-artwork-gradient);

config/_default/hugo.yml

@@ -69,10 +69,10 @@ outputs:
     - HTML
   section:
     - HTML
-    - llmstxt
+    # llmstxt disabled for sections - using .md files via Lambda@Edge instead
   home:
     - HTML
-    - llmstxt
+    - llmstxt  # Root /llms.txt for AI agent discovery
 
 # Asset processing configuration for development
 build:

deploy/llm-markdown/README.md

@@ -56,6 +56,90 @@ node cypress/support/run-e2e-specs.js \
   --spec "cypress/e2e/content/markdown-content-validation.cy.js"
 ```
 
+## Testing in AWS Console
+
+You can test the Lambda function directly in the AWS Console using the Test feature:
+
+### Single Page Request
+
+```json
+{
+  "Records": [
+    {
+      "cf": {
+        "request": {
+          "uri": "/influxdb3/core/get-started/index.md",
+          "querystring": "",
+          "headers": {
+            "host": [
+              {
+                "key": "Host",
+                "value": "docs.influxdata.com"
+              }
+            ]
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+### Section Aggregation Request
+
+```json
+{
+  "Records": [
+    {
+      "cf": {
+        "request": {
+          "uri": "/influxdb3/core/get-started/index.section.md",
+          "querystring": "",
+          "headers": {
+            "host": [
+              {
+                "key": "Host",
+                "value": "docs.influxdata.com"
+              }
+            ]
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+**Expected Response**: Lambda\@Edge origin-request handlers return a modified request object (not the final response). The function should return the request unchanged since it's handled by S3.
+
+## Code Architecture
+
+### CommonJS Module System
+
+The Lambda function uses CommonJS (`require`/`module.exports`) instead of ES6 modules (`import`/`export`) because:
+
+1. **Lambda\@Edge Compatibility**: Lambda\@Edge Node.js 18 runtime works best with CommonJS
+2. **No package.json type field**: The package.json must NOT include `"type": "module"`
+3. **Shared Library**: The markdown-converter library (`scripts/lib/markdown-converter.js`) has been converted to CommonJS for Lambda compatibility
+
+### Key Files
+
+- **`index.js`**: Lambda handler using CommonJS exports (`exports.handler`)
+- **`lib/s3-utils.js`**: S3 operations using CommonJS (`module.exports`)
+- **`scripts/lib/markdown-converter.js`**: Shared conversion library (CommonJS)
+- **`package.json`**: Dependencies WITHOUT `"type": "module"` field
+
+### Testing Module Loading
+
+To verify the Lambda function loads correctly:
+
+```bash
+cd deploy/llm-markdown/lambda-edge/markdown-generator
+node -e "const h = require('./index.js'); console.log('Handler type:', typeof h.handler);"
+```
+
+Expected output: `Handler type: function`
+
 ## Deployment
 
 ### Step 1: Install Lambda Dependencies

deploy/llm-markdown/lambda-edge/markdown-generator/deploy.sh

@@ -21,21 +21,85 @@ echo ""
 
 # Step 2: Package function
 echo "📦 Step 2: Packaging Lambda function..."
-rm -f function.zip
-zip -r function.zip index.js lib/ node_modules/ > /dev/null
+
+# Create temporary directory structure for packaging
+rm -rf .package-tmp
+mkdir -p .package-tmp/scripts/lib
+mkdir -p .package-tmp/data
+mkdir -p .package-tmp/lib
+
+# Copy Lambda function files
+cp index.js .package-tmp/
+cp -r lib/* .package-tmp/lib/
+cp -r node_modules .package-tmp/
+
+# Copy shared markdown converter library
+cp ../../../../scripts/lib/markdown-converter.js .package-tmp/scripts/lib/
+
+# Copy products.yml for product detection
+cp ../../../../data/products.yml .package-tmp/data/
+
+# Generate config.json with S3 bucket name
+cat > .package-tmp/config.json <<EOF
+{
+  "s3Bucket": "$S3_BUCKET"
+}
+EOF
+echo "   Generated config.json with S3_BUCKET=$S3_BUCKET"
+
+# Create ZIP from temp directory
+cd .package-tmp
+rm -f ../function.zip
+zip -r ../function.zip * > /dev/null
+cd ..
+
+# Clean up temp directory
+rm -rf .package-tmp
+
 PACKAGE_SIZE=$(du -h function.zip | cut -f1)
 echo "✅ Package created: function.zip ($PACKAGE_SIZE)"
 echo ""
 
 # Step 3: Check if IAM role exists
 echo "🔐 Step 3: Checking IAM role..."
-if aws iam get-role --role-name $ROLE_NAME --region $AWS_REGION > /dev/null 2>&1; then
+echo "DEBUG: About to call AWS CLI for role: $ROLE_NAME"
+
+# Temporarily disable exit-on-error for AWS CLI call
+set +e
+
+# Capture stdout and stderr separately
+ROLE_ARN=$(aws iam get-role --role-name $ROLE_NAME --query 'Role.Arn' --output text 2>/tmp/deploy-error.txt)
+ROLE_EXIT_CODE=$?
+ROLE_ERROR=$(cat /tmp/deploy-error.txt 2>/dev/null)
+
+# Re-enable exit-on-error
+set -e
+
+echo "DEBUG: AWS CLI returned - Exit code=$ROLE_EXIT_CODE, ARN='$ROLE_ARN', Error='$ROLE_ERROR'"
+
+if [ $ROLE_EXIT_CODE -eq 0 ] && [[ "$ROLE_ARN" =~ ^arn:aws:iam ]]; then
     echo "✅ IAM role '$ROLE_NAME' already exists"
-    ROLE_ARN=$(aws iam get-role --role-name $ROLE_NAME --region $AWS_REGION --query 'Role.Arn' --output text)
+elif [[ "$ROLE_ERROR" =~ "ExpiredToken" ]]; then
+    echo "❌ AWS SSO session expired"
+    echo ""
+    echo "   Run the following command to refresh your session:"
+    echo "   aws sso login"
+    echo ""
+    exit 1
+elif [ $ROLE_EXIT_CODE -eq 255 ]; then
+    echo "❌ AWS CLI error - check your credentials"
+    echo "   Error: $ROLE_ERROR"
+    echo ""
+    echo "   Make sure AWS credentials are configured:"
+    echo "   - aws sso login (for SSO)"
+    echo "   - aws configure (for access keys)"
+    echo ""
+    exit 1
 else
-    echo "⚠️  IAM role not found. Creating..."
-    echo "   Run the following command:"
+    echo "⚠️  IAM role not found"
+    echo "   Error: $ROLE_ERROR"
     echo ""
+    echo "   Run the following command to create it:"
     echo "   ./create-iam-role.sh"
     echo ""
     exit 1

deploy/llm-markdown/lambda-edge/markdown-generator/index.js

@@ -8,18 +8,18 @@
  * Triggers for: *.md file requests
  */
 
-import { fetchHtmlFromS3, listChildPages } from './lib/s3-utils.js';
-import {
+const { fetchHtmlFromS3, listChildPages } = require('./lib/s3-utils.js');
+const {
   convertToMarkdown,
   convertSectionToMarkdown,
-} from '../../../../scripts/lib/markdown-converter.js';
+} = require('./scripts/lib/markdown-converter.js');
 
 /**
  * Lambda@Edge handler
  * @param {Object} event - CloudFront origin request event
  * @returns {Object} CloudFront response object
  */
-export const handler = async (event) => {
+exports.handler = async (event) => {
   const request = event.Records[0].cf.request;
   const uri = request.uri;
 

deploy/llm-markdown/lambda-edge/markdown-generator/lib/s3-utils.js

@@ -10,9 +10,27 @@ const {
   ListObjectsV2Command,
 } = require('@aws-sdk/client-s3');
 
-// S3 bucket configuration (from environment or hardcoded for staging)
-const BUCKET_NAME = process.env.S3_BUCKET || process.env.S3_TEST_BUCKET;
-const s3Client = new S3Client({ region: 'us-east-1' });
+// S3 bucket configuration
+// Try environment variable first (works for testing), then config file
+let BUCKET_NAME = process.env.S3_BUCKET;
+
+if (!BUCKET_NAME) {
+  try {
+    const config = require('../config.json');
+    BUCKET_NAME = config.s3Bucket;
+  } catch (err) {
+    throw new Error(
+      'S3_BUCKET must be set via environment variable or config.json'
+    );
+  }
+}
+
+// Configure S3 client with proper region handling
+const s3Client = new S3Client({
+  region: process.env.AWS_REGION || 'us-east-1',
+  // Follow bucket region redirects automatically
+  followRegionRedirects: true,
+});
 
 /**
  * Fetch HTML content from S3

deploy/llm-markdown/lambda-edge/markdown-generator/package.json

@@ -3,7 +3,6 @@
   "version": "1.0.0",
   "description": "Lambda@Edge function for on-demand markdown generation from HTML",
   "main": "index.js",
-  "type": "module",
   "scripts": {
     "install-deps": "npm install",
     "package": "zip -r function.zip index.js lib/ node_modules/",
@@ -12,6 +11,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.484.0",
     "jsdom": "^23.0.1",
+    "js-yaml": "^4.1.0",
     "turndown": "^7.1.2"
   },
   "devDependencies": {},

deploy/llm-markdown/lambda-edge/markdown-generator/yarn.lock

@@ -1126,6 +1126,11 @@ agent-base@^7.1.0, agent-base@^7.1.2:
   resolved "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz"
   integrity sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==
 
+argparse@^2.0.1:
+  version "2.0.1"
+  resolved "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz"
+  integrity sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==
+
 asynckit@^0.4.0:
   version "0.4.0"
   resolved "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz"
@@ -1346,6 +1351,13 @@ is-potential-custom-element-name@^1.0.1:
   resolved "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz"
   integrity sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==
 
+js-yaml@^4.1.0:
+  version "4.1.1"
+  resolved "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz"
+  integrity sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==
+  dependencies:
+    argparse "^2.0.1"
+
 jsdom@^23.0.1:
   version "23.2.0"
   resolved "https://registry.npmjs.org/jsdom/-/jsdom-23.2.0.tgz"

layouts/_default/landing-influxdb.html

@@ -52,7 +52,11 @@ <h3>Monitor & Alert</h3>
       </div>
     </div>
 
-    <!-- {{ partial "article.html" . }} -->
+    <div class="article">
+      <article class="article--content">
+        {{ partial "article/format-selector.html" . }}
+      </article>
+    </div>
     <div class="copyright">© {{ now.Year }} InfluxData, Inc.</div>
   </div>
 </div>