Add AppAdSwap to a Docusaurus site

By Luis Krin · Updated · All install guides

The snippet

Every platform needs the same two things: a slot where the card shows, and the script. Replace SITE_ID with your site's ID. The Sites page in your dashboard shows this snippet with the ID already filled in.

HTML
<div data-appadswap="SITE_ID" data-format="card"></div>
<script src="https://appadswap.com/w.js" async></script>

In Docusaurus, load the script with the scripts option in docusaurus.config.js, and put the slot in an MDX page as a self-closing div. Add async: true to the script entry, because Docusaurus scripts block rendering by default.

Step 1: add the script to the config

Docusaurus's scripts option takes an array of scripts to load, each either a URL string or an object of attributes. They are inserted in the HTML <head>. Docusaurus notes that scripts added this way are render-blocking, so use the object form with async: true:

// docusaurus.config.js
const config = {
  // ...your existing options
  scripts: [
    { src: "https://appadswap.com/w.js", async: true },
  ],
}
// keep your existing export of config

Rebuild or restart the dev server after changing the config; config changes aren't hot-reloaded.

Step 2: add the slot to a page

In an .md or .mdx page, use a self-closing JSX div. MDX needs JSX syntax, so the <div ...></div> pair that works in plain HTML should be written self-closed:

Thanks for reading.

<div data-appadswap="SITE_ID" data-format="card" />

A card on every doc page

An MDX page holds one slot, in that one page. To put the card on every doc page, you add it to a theme component through Docusaurus's swizzling, which lets you copy a theme component into your project and edit it. The doc page footer is a natural place, below the content. Docusaurus's swizzling documentation explains the command and which components are safe to swizzle. Wrap the slot in a small component and import it there:

// src/components/AppAdSwapSlot.jsx
export default function AppAdSwapSlot() {
  return <div data-appadswap="SITE_ID" data-format="card" />
}

Navigation inside the site

Docusaurus is a single-page app: moving between docs doesn't reload the page. The widget watches for new slots and fills any that are added after it has loaded, so a slot on a page you navigate to still fills.

Corner card, no slot

For the corner format, give the script entry the attributes and skip the slot:

scripts: [
  { src: "https://appadswap.com/w.js", async: true, "data-appadswap": "SITE_ID", "data-format": "corner" },
],

Check it works

Run npm run build and serve the output, or deploy a preview, then open a page with a slot. The Sites page in your dashboard flips from unverified to live on its own once the widget has loaded on the registered address.

If it doesn't work

  • The script tag isn't in the page source. The config change wasn't picked up. Restart the dev server or rebuild.
  • MDX fails to compile. An unclosed div is the usual cause. Self-close it.
  • The slot appears in a page but stays empty. The script isn't loading; check the Network tab for w.js.

Source

Docusaurus's configuration reference, which documents scripts. Next: other install guides, or add your app.

Other platforms.

Installed?Add your app.

Add your appAll install guides