From 45e1cba2a13f3ebd3d4bbd3c2d809175ac5139c4 Mon Sep 17 00:00:00 2001 From: Youssef El Allali Date: Wed, 14 Oct 2026 18:03:36 +0100 Subject: [PATCH] docs: add interactive demo visibility rule to style guide --- .claude/skills/doc-feedback.md | 1 + docs/content-guidelines.md | 24 ++++++++++++++++++++++++ 2 files changed, 25 insertions(+) diff --git a/.claude/skills/doc-feedback.md b/.claude/skills/doc-feedback.md index b5e554753..60c93c134 100644 --- a/.claude/skills/doc-feedback.md +++ b/.claude/skills/doc-feedback.md @@ -61,6 +61,7 @@ Review Progress: - [ ] Content scannable (headings, lists, white space) - [ ] Active voice, second person - [ ] Troubleshooting included where appropriate +- [ ] Interactive demos wrapped in `` (see Interactive Demos in content-guidelines.md) - [ ] Correct tab/section placement, naming conventions followed - [ ] No redundant sidebar labels - [ ] docs-structure validation passes (if docs.json / frontmatter changed) diff --git a/docs/content-guidelines.md b/docs/content-guidelines.md index a797e45f4..637226cb6 100644 --- a/docs/content-guidelines.md +++ b/docs/content-guidelines.md @@ -92,6 +92,30 @@ description: "Concise description explaining page purpose and value" - Use **ParamField** for API parameters, **ResponseField** for API responses - Use **Expandable** for nested object properties or hierarchical information +### Interactive Demos + +Mintlify inlines the full source of every imported JSX component into a page's Markdown export (`.md` URLs and `Accept: text/markdown`). An unwrapped demo adds tens of kilobytes of code that agents read but can't use. + +- Wrap every interactive demo component (for example, `PaymentsDemo` or `StablecoinDemo`) in `` +- Put the `## Demo` heading and any callout that only describes the demo (such as a mock or Vibenet disclaimer) inside the same block +- Keep content agents need, such as version notes, contract addresses, warnings, and Steps, outside the block +- Wrap each use of the component, including a second inline demo later on the page; the source is only dropped when every use is inside a humans-only block +- Leave a blank line after `` and before `` so the Markdown inside renders + +```mdx Title Interactive demo pattern + + +## Demo + + + + +The demo above is mock only. + + + +``` + --- ## Specification Pages