Docusaurus installation
Docusaurus Docs Testimonial Widget Embed
Docusaurus builds a single page application, and its own docs warn that script tags run only on the first page load, not on later page transitions. That shapes the whole install. The StoryProof script goes in the scripts array of docusaurus.config.js, the div comes from a tiny React component used in MDX, and links into that page use the pathname:// prefix so the browser loads it outright.
- embed.js in the scripts config, set to async
- A React component you import into MDX
- pathname:// links that skip the SPA router
Docusaurus snippets
Config, component, MDX page and link
Fill in the widget id. Snippet 1 adds the script to your config, snippet 2 is the component, snippet 3 is an MDX page that renders it, and snippet 4 is how other docs should link there.
Part 1 · Snippet 1: scripts config
docusaurus.config.js
// docusaurus.config.js (add to the existing config object)
export default {
// ...title, url, presets and the rest of your config
scripts: [
// async, because entries here are render blocking otherwise
{ src: 'https://app.storyproof.io/embed.js', async: true },
],
};Part 2 · Snippet 2: the component
src/components/StoryProofWidget.js
// src/components/StoryProofWidget.js
export default function StoryProofWidget({ id }) {
// The embed script fills this element; keep it empty.
return <div data-storyproof-widget={id} />;
}Part 3 · Snippet 3: an MDX page
src/pages/customers.mdx (or a doc under docs/)
---
title: Who uses our API
---
import StoryProofWidget from '@site/src/components/StoryProofWidget';
Teams building on the platform describe what changed for them.
<StoryProofWidget id="YOUR_WIDGET_ID" />Part 4 · Snippet 4: linking from other docs
Any Markdown or MDX file
<!-- In any other doc, link to that page outside the SPA router -->
Curious what other teams think? See [who uses our API](pathname:///customers).Run npm run build then npm run serve, open /customers directly, and confirm the testimonials render. Then follow a pathname:// link to it from another doc and check again.
Built in your browser from the id you enter. No data leaves the page.
The problem, solved
Where Docusaurus fights an embed, and the fix
- Problem 1
Pasted HTML in MDX breaks the build
Docusaurus says anything that looks like HTML in MDX is JSX, so attribute syntax and inline styles follow React rules, not HTML ones.
How StoryProof solves it
The StoryProof embed needs only an empty div carrying the widget id, which a three line component returns without any HTML to translate.
- Problem 2
A third party script slowing first paint
The Docusaurus config reference notes that entries in scripts are render blocking unless marked async or defer.
How StoryProof solves it
Snippet 1 sets async: true, and the one file then serves every StoryProof widget on the page it loads with.
- Problem 3
Empty widget after a sidebar click
Docusaurus states that scripts execute the first time the page loads and do not re-execute on transitions between pages.
How StoryProof solves it
Link to the testimonial page with pathname://, which Docusaurus documents as a non SPA link, so the page and its script load together.
- Problem 4
Who signed off on this quote?
Docs teams answer to engineering and legal, and an unvetted quote on a public API site causes awkward questions.
How StoryProof solves it
Nothing appears in a StoryProof widget until someone approves it, and you choose which approved testimonials each widget id carries.
- Problem 5
Proof wanted in the navbar or footer
Navbar and footer items are config driven links, not pages that can hold a component.
How StoryProof solves it
Point those links at your hosted Wall of Love, which every StoryProof plan includes, and keep the embedded widget for one MDX page.
In StoryProof
Set it up in a Docusaurus site
Step 1 of 4
Add embed.js to the scripts array
In docusaurus.config.js add an object with src and async: true to scripts. Docusaurus accepts any extra attributes on that object.
Step 2 of 4
Create the component
Save snippet 2 in src/components. It returns the div only; the script from step one does the rest.
Step 3 of 4
Use it from an MDX page
Import the component with the @site alias at the top of an .mdx file and render it with your widget id. A page in src/pages keeps it out of the docs sidebar.
Step 4 of 4
Fix the links that lead there
Write links to that page with the pathname:// prefix, then build, serve and test a click through as well as a direct visit.
Where a reader comes from, and whether the widget is ready
Before you start
Limits on Docusaurus
Docusaurus docs as of 2026-11-14
The scripts field, MDX rules, client module lifecycles and pathname:// behaviour follow docusaurus.io as read on 2026-11-14. Nobody has run this on a live Docusaurus site yet.
Sidebar arrivals
A reader who reaches a widget page through the sidebar gets a client side transition. Placing the widget on a standalone page in src/pages, reached by pathname:// links, avoids most of these.
Script on every page
The scripts array adds embed.js to every page of the site, including those without a widget. It is async, so it does not block rendering.
No Docusaurus plugin
StoryProof has no Docusaurus plugin or theme. The config entry and the component are the full integration.
Badge until a paid plan
A small "Powered by StoryProof" badge appears on widgets until Pro.
FAQ
Questions people ask
Short answers to what usually comes up next.
Can I put the script tag inside the MDX file instead?
Docusaurus says script tags run only on the first page load. The scripts config is the documented route, and it keeps a single copy for the whole site.
Should the widget go on a doc page or a standalone page?
A standalone page in src/pages is easier, because you control every link to it. A doc page works too, but readers often reach it through the sidebar.
Does headTags do the same job as scripts?
headTags inserts arbitrary tags in the head, so it could carry the script. The scripts field is shorter for this and documents the async option directly.
Will versioned docs need the component in each version?
The component lives in src/components, shared across versions. Only MDX files in a given version need the import line if you want the widget there.
Still have a question? Ask the StoryProof team or book a demo.
Bring customer proof into your Docusaurus site
Approve testimonials in StoryProof, then render one component on an MDX page.
Sources
- docusaurus.config.js, Docusaurus Documentation. Checked 2026-11-14.
- MDX and React, Docusaurus Documentation. Checked 2026-11-14.
- Client architecture, Docusaurus Documentation. Checked 2026-11-14.
- Routing, Docusaurus Documentation. Checked 2026-11-14.
Last updated 2026-11-14.