How published pages run

A DocPin page is your HTML, served inside a DocPin page at your link (https://acme.docpin.it/plan, https://docs.acme.com/plan, or a short link like https://docpin.it/Ab3dE). Knowing how that works lets you build interactive pages that behave well.

The short version

The frame

Your page runs in a sandboxed frame on its own address under docpinusercontent.com. Each published version gets its own address. The DocPin page around it shows the link, the "Pinned with DocPin" badge, and the password or sign-in screen for private pages.

What works inside the frame:

• Scripts, forms, dialogs (alert, confirm), downloads, fullscreen, copy to clipboard, and window.open.
• Fetching from any API that allows cross-origin requests (CORS). Your page's origin is opaque (null), so the API must allow *.
• Your own files from the same upload, with relative links (styles.css, img/logo.png, about.html).

What doesn't:

• Cookies and IndexedDB. They're blocked. Use localStorage (below) or the URL.
• Navigating the whole tab to another site from a script. location.href = "https://…" and window.top.location fail. Use a link or window.open.
• Reading the DocPin page around you, its cookies or its storage.
• Camera, microphone, location, payment and USB.

Links

• Links to other sites open in a new tab, so your page stays open. DocPin adds target="_blank" and rel="noopener" when someone clicks them.
• mailto: and tel: links also open in a new tab, which hands them to the mail or phone app.
• Links to #ids scroll within the page, as normal.
• Links between files in your upload (about.html) open inside the frame. The address bar keeps the page's own link.

URL state

DocPin connects your page's ?query and #hash to the link in the address bar, in both directions:

• In: opening https://acme.docpin.it/plan?tab=pricing#faq loads your page with location.search === "?tab=pricing" and location.hash === "#faq". If #faq matches an element's id, the browser scrolls to it.
• Out: when your page changes its query or hash, through history.replaceState, history.pushState, setting location.hash, or a #link, DocPin updates the address bar to match. Copying the link then reopens that exact view.

The query and hash also survive the password screen, people sign-in, and redirects from an old link after a page is renamed or moved.

<nav>
  <button data-tab="overview">Overview</button>
  <button data-tab="pricing">Pricing</button>
</nav>
<script>
  const params = new URLSearchParams(location.search);
  function show(tab) {
    document.querySelectorAll("[data-tab]").forEach((b) => b.setAttribute("aria-pressed", b.dataset.tab === tab));
    // …show the matching section…
  }
  show(params.get("tab") || "overview");
  document.querySelectorAll("[data-tab]").forEach((b) => b.addEventListener("click", () => {
    const q = new URLSearchParams(location.search);
    q.set("tab", b.dataset.tab);
    history.replaceState(null, "", "?" + q + location.hash);
    show(b.dataset.tab);
  }));
</script>

Tips:

• Use replaceState for UI state like tabs and filters, so the back button isn't flooded. Use pushState only for things that feel like separate pages.
• Keep state small: up to about 4,000 characters of query plus hash.
• Use the URL for state people share. Use storage for state that's personal (a visitor's draft, a dismissed banner).
• Don't put anything secret in the URL. It's shown in the address bar and stays in browser history.

Browser storage

localStorage and sessionStorage work, even though the sandbox normally blocks them:

• localStorage is kept for this page in the visitor's browser, under the page's link (for example acme.docpin.it). It survives reloads and new versions of the page.
  • Each page has its own storage. Pages don't see each other's.
  • Up to about 1 MB per page. Past that, setItem throws QuotaExceededError.
  • It's still the visitor's browser: clearing site data removes it, and it doesn't follow them to another device.
• sessionStorage lasts for the current visit only.

The standard API works: getItem, setItem, removeItem, clear, key(i), length, and localStorage.name = value. Values are strings, so use JSON.stringify and JSON.parse for objects.

Storage is per visitor. To show the same data to everyone, use page data.

Link previews and icons

When someone shares a page's link in Slack, iMessage, email or social media, the preview comes from DocPin, using what your page says about itself:

Without an og:image, DocPin draws a share card from the page's title and link. Private pages (password or people-only) always show a "Private page" card, with no title, description or image, because a preview shouldn't reveal what's inside. Secret links show the generated card but not your description or image.

<title>Q4 proposal for Acme</title>
<meta name="description" content="Pricing, timeline and next steps for the Q4 rollout.">
<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>📊</text></svg>">

The docpin object

DocPin's script adds a global docpin before your own scripts run:

If your page might also be opened outside DocPin (for example, as a local file), check before using it: if (window.docpin) { … }.

Checklist for AI-generated pages

When an AI app writes a page for DocPin, it should:

1. Send one complete, self-contained HTML document, or index.html plus its files.
2. Keep any state worth sharing in the URL (replaceState), and read it on load.
3. Use localStorage only for per-visitor state, and wrap it in try/catch.
4. Read changing numbers from docpin.data() / docpin.onData() and show an empty state when there's no data.
5. Use plain <a href> links to other sites, never location.href to another site.
6. Avoid cookies, IndexedDB, service workers, and anything that needs the camera or location.
7. Keep secrets out of the HTML, the URL and the page data.
8. Give the page a clear <title> and <meta name="description"> for link previews, and optionally a favicon.