Skip to content

feat: Amplify Gen 2 CDK backend — CloudFront + Lambda for Accept: text/markdown#330

Open
Nonnyjoe wants to merge 2 commits into
mainfrom
feat/amplify-lambda
Open

feat: Amplify Gen 2 CDK backend — CloudFront + Lambda for Accept: text/markdown#330
Nonnyjoe wants to merge 2 commits into
mainfrom
feat/amplify-lambda

Conversation

@Nonnyjoe
Copy link
Copy Markdown
Member

@Nonnyjoe Nonnyjoe commented May 25, 2026

Summary

Adds the Amplify Gen 2 CDK backend that powers HTTP content negotiation for the docs site.

  • amplify/functions/markdown-negotiation/ — Amplify-managed Lambda (docs-markdown-negotiation) visible in Amplify Console → Functions. Rewrites Accept: text/markdown requests to .md paths and proxies to the Amplify origin.
  • amplify/custom/markdown-negotiation/ — CDK construct that creates a CloudFront distribution with the Lambda Function URL as its origin. Cache policy varies on the Accept header so HTML and Markdown variants cache separately.
  • amplify/backend.ts — wires Lambda and CloudFront together, attaches a Function URL, passes the hostname to the CloudFront construct, and emits the distribution domain as a CloudFormation output.
  • amplify.yml — adds the backend.phases.build CDK deploy step alongside the existing frontend build. Also includes rewrite rules and CDN cache headers (superset of what feat/llm-readability added).
  • Removes package-lock.json (project uses yarn); adds Amplify Gen 2 and AWS CDK dependencies to package.json and yarn.lock.

Dependencies

This PR is currently deployed and being monitored on staging. Merge feat/llm-readability (#329) first.

Infrastructure notes

  • CloudFront distribution domain is emitted as MarkdownNegotiationDomain in the MarkdownNegotiationStack CloudFormation stack.
  • DOCS_DOMAIN env var drives both the CloudFront alternate domain and llms.txt base URLs. Defaults to staging.docs.cartesi.io when unset.
  • DOCS_CERT_ARN is optional — omit for staging (no custom domain), set to an ACM cert ARN (us-east-1) for production.

Test plan

  • Amplify build completes with backend CDK deploy phase
  • docs-markdown-negotiation Lambda visible in Amplify Console → Functions
  • MarkdownNegotiationStack appears in CloudFormation with CREATE_COMPLETE or UPDATE_COMPLETE
  • curl -H "Accept: text/markdown" https://docs.cartesi.io/cartesi-rollups/overview returns 200 OK with Content-Type: text/markdown
  • Normal browser request to https://docs.cartesi.io/cartesi-rollups/overview returns HTML (no regression)

Closes #328

@Nonnyjoe Nonnyjoe force-pushed the feat/amplify-lambda branch from 8e1bcba to 684a373 Compare May 25, 2026 18:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

AI-readable docs: llms.txt, .md content negotiation, and CloudFront/Lambda delivery

1 participant