Add LLM-friendly documentation features #16998
Conversation
…er menu Add LLM-friendly documentation features with markdown output and helper menu This adds a set of features to make Pulumi documentation more accessible to LLMs and AI-powered tools, inspired by Mintlify's approach. The main addition is an LLM helper menu in the docs sidebar that gives users several options for working with documentation in AI tools. Users can copy the page as markdown for pasting into an LLM, view the raw markdown version in a new tab, or directly open the page in ChatGPT or Claude with a pre-filled prompt that tells the AI to read from the markdown URL. On the backend, Hugo now generates markdown versions of all docs pages alongside the HTML versions. These markdown files contain the raw content with Hugo shortcodes preserved, which modern LLMs are trained to understand. We also added a Lambda@Edge function that performs content negotiation - when a client requests a docs page with Accept: text/markdown, CloudFront automatically serves the markdown version instead of HTML. This allows AI tools to fetch markdown directly when they crawl the site. The implementation uses the official ChatGPT and Claude logos, styles the menu to match existing sidebar elements, and includes all the polish you'd expect from a production feature. Infrastructure changes are gated behind a doMarkdownContentNegotiation config flag.
joeduffy
changed the title
This comment was marked as outdated.
This comment was marked as outdated.
|
Your site preview for commit 0c1a9f9 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16998-0c1a9f94.s3-website.us-west-2.amazonaws.com. |
- Introduced a new feature for serving markdown versions of documentation based on the Accept header. - Updated `BUILD-AND-DEPLOY.md` with detailed configuration and usage instructions. - Minor adjustments to `single.md` and `list.md` layout files for consistency. - Updated `package.json` to include a trailing comma for better formatting.
|
Your site preview for commit 4042ede is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16998-4042ede7.s3-website.us-west-2.amazonaws.com. |
… Markdown support
|
Your site preview for commit 37c84cb is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16998-37c84cb1.s3-website.us-west-2.amazonaws.com. |
This comment was marked as resolved.
This comment was marked as resolved.
|
Your site preview for commit 0d83a56 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16998-0d83a565.s3-website.us-west-2.amazonaws.com. |
|
Your site preview for commit e7dc984 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16998-e7dc984a.s3-website.us-west-2.amazonaws.com. |
|
Your site preview for commit 411a161 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16998-411a161a.s3-website.us-west-2.amazonaws.com. |
- Add try-catch blocks to copyPage() and copyUrl() methods to handle clipboard write failures - Fix mermaid race condition by using startOnLoad: false and manually calling mermaid.run() after preserving source - Ensures data-mermaid-source attribute is set before mermaid renders diagrams Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
Your site preview for commit 8a9aacf is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-16998-8a9aacfd.s3-website.us-west-2.amazonaws.com. |
|
I did a significant refactoring of this. It's all client-side now, no Hugo, no infra changes. I also refined the markdown output to correct all the default Turndown generated by default. The markdown it generates is really clean now. Finally, I added a simple "Copy URL" option. @cnunciato I'm inclined to merge this now, but I wouldn't mind a sanity check, please 🙂 (turning on auto merge) |
Work in progress: The AWS config changes require more validation.
This adds LLM-friendly features to make Pulumi docs more accessible to AI tools. The implementation is inspired by Mintlify's LLM helper menu and includes both frontend UI improvements and backend content negotiation.
What's New
There's now an "LLM helper" dropdown menu in the docs sidebar that gives users several ways to work with documentation in AI tools. You can copy a page as markdown for pasting into an LLM, view the raw markdown version, or directly open ChatGPT or Claude with a prompt that tells the AI to read from the page's markdown URL. The menu uses the official logos for ChatGPT and Claude and is styled to match the existing sidebar links.
Hugo now generates markdown versions of docs pages alongside HTML. These are available at URLs like
/docs/foo/index.mdand contain clean markdown with Hugo shortcodes preserved. Modern LLMs understand Hugo syntax, so they can read these files without issue. The markdown generation uses Hugo's built-in support for custom output formats withisPlainText: true.For content negotiation, we added a Lambda@Edge function that detects the
Accept: text/markdownheader and rewrites requests to serve the markdown version. CloudFront caches responses based on the Accept header so both HTML and markdown versions are cached independently. The Lambda function is controlled by adoMarkdownContentNegotiationconfig flag so it can be enabled incrementally.Testing
Navigate to any docs page and click the "Copy Page" dropdown in the right sidebar. Try each menu option. You can also directly visit a markdown URL like
/docs/iac/concepts/index.mdor test content negotiation withcurl -H "Accept: text/markdown" https://pulumi.com/docs/iac/concepts/.