← All posts

Embed a Live Code Paste Inside Docs and Forum Replies

How to embed a live SnipShare paste in a post, a docs page or a bbPress reply, what readers see for private, expired or locked pastes, and the size limits.

You can embed a live paste from SnipShare three ways: put the paste URL on its own line in a post or page, drop in the [snipshare] shortcode, or paste the URL into a bbPress topic or reply. Each one renders the code in place with syntax highlighting and a link back to the full paste. Nothing is copied into your page. Because the code stays in the paste, when the paste changes, every page that shows it changes too.

That one design choice is the whole business case, because code snippets in documentation rot faster than the prose around them. Say a framework renames a function and a hook gets a new argument: the tutorial you published last spring now teaches something that fails. Keep the snippet in forty places as pasted text and you fix forty places. Keep it in one paste and the fix happens once.

Below, you will find how each embed method works, what a reader sees when a paste can’t be shown, the size rules, and a short checklist to run before you ship embeds into a docs site or a support forum.

The three ways to embed a paste

A URL on its own line. SnipShare registers itself with WordPress as an oEmbed provider, matching the paste address on your own site. Drop a paste URL on its own line in the post body and WordPress turns it into an embedded viewer, the same way it does for other embeddable links. Test it once in your own editor, since themes and editors differ. Tutorial authors get the easiest route here, because there is nothing to remember beyond the link.

The [snipshare] shortcode. Five attributes are available: id, hash, file, lines and height. Use hash or id to say which paste you mean. Add file to show one file from a multi-file paste (if the name doesn’t match, you get the first file). Add lines="5-20" to show only a slice, and height to cap the box in pixels and let it scroll.

When a tutorial needs to point at the exact twelve lines that matter in a three-hundred-line file, the shortcode is the right tool. Leave the whole file in the paste, and show only the part you’re discussing.

A bare URL in bbPress or BuddyPress. bbPress doesn’t run shortcodes in topics and replies, so SnipShare converts bare paste URLs instead. SnipShare hooks the topic and reply content and swaps each paste URL for the embedded viewer. BuddyPress activity updates get the same treatment. Unlike WordPress’s own autoembed, which wants the URL alone in its paragraph, this one also works when the URL sits inside a sentence. Any URL that is already inside a link you wrote is left alone, and only the paste page itself matches, not the raw or edit addresses.

Which pastes can be embedded

Some pastes are not embeddable, and the rules are worth knowing before you promise a reader a live example.

  • Public pastes embed by URL or by shortcode.
  • Unlisted pastes embed by URL, and by shortcode only if you use hash. Numeric id values in the shortcode work for public pastes only, because an unlisted paste’s link is its secret and an ID is easy to guess.
  • Private pastes don’t embed through oEmbed at all, and the shortcode shows them only to their owner and site moderators.
  • Burn-after-read pastes are never advertised through the oEmbed route.

The unlisted rule deserves a second look, because putting an unlisted paste into a public docs page publishes its link to everyone who views the page source. Treat unlisted as “not listed”, not as “hidden”. Content that shouldn’t be public doesn’t belong in an embed on a public page. Our guide to public, unlisted and private pastes goes through the difference.

What readers see when an embed can’t show the code

Most embed guides skip this section, and it’s where support tickets come from. Pastes change state over time: someone makes one private, it expires, an author deletes it. In each case, the code behaves as follows.

The oEmbed endpoint (/wp-json/snipshare/v1/oembed) answers with a 404 for a private paste, a burn-after-read paste, a trashed paste, an expired paste and a paste that doesn’t exist. All five get the same “Paste not found” response, so the endpoint doesn’t reveal which of those it was. While WordPress resolves a paste on your own site, a failed lookup means the URL simply stays a plain link in the post. Nothing breaks, and nothing leaks.

A password-protected paste is different, and it is not a 404. The embed frame loads, but instead of code it shows a locked card: a message saying the paste is password protected, and an “Open paste” link that goes to the full page where the reader can enter the password. Because embeds never unlock a paste, a reader can’t type the password into the frame. The shortcode behaves the same way for locked pastes, with a “View paste” link.

The frame loads the paste each time the page is viewed, so a paste that changes state after you embedded it shows its new state. Make an embedded paste private later, and readers see “Paste not found.” inside the frame. Let it expire, and they see a message that it has expired. Embeds in old tutorials can therefore go quiet without the page itself changing, which we’ll come back to in the checklist.

Size limits, and what the frame looks like

Embeds are iframes, and the plugin picks their size rather than leaving it to the theme.

  • Width is clamped between 300 and 800 pixels.
  • Height is worked out from the paste’s line count and clamped between 150 and 500 pixels.

The height formula is simple: a 36 pixel header, 24 pixels of padding, and 24 pixels per line, using the longest file in the paste. For three made-up pastes, the arithmetic runs like this:

  • 4 lines: 36 + 24 + 96 = 156 pixels.
  • 10 lines: 36 + 24 + 240 = 300 pixels.
  • 20 lines: 36 + 24 + 480 = 540, capped at 500, so the code scrolls inside the frame.

Short snippets get short frames, and long ones top out at 500 pixels. To keep a docs page free of tall blocks, rely on the cap, and the lines attribute on the shortcode lets you cut a long file down to the part that matters.

Inside, the frame is a dark code view with line numbers. The header carries the file name and language, plus a link that says “View on” followed by your site name. A multi-file paste shows the first file in the frame, so if the second file matters, either link to the paste or use the shortcode with file.

Sandboxing uses allow-scripts allow-popups. Scripts are allowed because the syntax highlighter needs them, and popups are allowed so the “View on” link can open a new tab. Same-origin access is not granted, so the framed page’s scripts can’t reach into the page that hosts it. That matters on a docs site where you’d rather not give an embedded widget any hold on the surrounding page.

Using it for docs and tutorials

Tutorials are a good fit because the snippet is the product. Think about how a typical how-to is built: a few paragraphs, a block of code, a few more paragraphs, another block. Make each block an embed and the page becomes a thin layer of explanation over snippets that you maintain in one place.

For a docs team, a workable setup looks like this. Keep snippets as pastes owned by one maintainer account, with public visibility, and reference them from pages by URL or shortcode. Edit the paste when the API changes. Our use case for tutorials that replace Gist embeds walks through the setup in more detail, including keeping tutorial code in collections.

Easy to miss is a second benefit: the snippet lives on your own domain, so a reader who clicks “View on” lands on your site, not someone else’s. Both the code page and the tutorial page belong to you and link to each other.

Expectations need a check, though. An embed is a viewer, not a runner, and it shows highlighted code, line numbers and a link. Does your tutorial need a reader to execute the code? Say so in the prose and tell them where to run it.

Using it for forum answers

In forum answers, embeds earn their keep with the least effort. A support reply that includes forty lines of config, pasted straight into a bbPress reply, makes the thread hard to scan. Swap in a paste URL and the same reply becomes two sentences and a tidy code frame.

Since bbPress auto-embed is on by default, there’s nothing to switch on. The setting is under SnipShare, then Settings, then the Integrations tab, in the bbPress section, labelled “Paste Embeds”. That section appears only when bbPress is active. Next to it sits a “Reply Toolbar Button” setting, also on by default, which adds an “Insert Paste” button to the topic and reply forms. For a logged-in member it lists their ten most recent pastes, plus a field for a paste hash, and inserts the URL so autoembed can turn it into a preview.

For a support team, a small habit makes this pay off: answer with a paste, not a wall of code. Once a customer posts an error, the reply can carry a corrected config as an embed. Later, if the config needs a tweak, you edit the paste and every thread that links to it updates. Our walkthrough on bbPress code attachments covers the forum side, and the post on building a developer community around shared snippets covers the wider setup.

Watch one place closely. Members paste their own URLs, and a member can paste a link to a paste that is unlisted. That link embeds, and anyone reading the thread can see it. On a public forum, tell members that an unlisted paste in a public thread is public in practice.

Embedding a paste on another site

The oEmbed endpoint is a standard one, and every single paste page carries a discovery link in its head that points to it. A different WordPress site, or any tool that understands oEmbed discovery, can therefore embed a public paste from yours without extra setup on their side. This helps when you publish a library and want other people’s tutorials to show your canonical example from your domain.

Of course, the same visibility rules apply there. Public and unlisted pastes return an embed. Private, burned, trashed or expired ones return a 404 to the remote site. You don’t need to do anything to stop the remote site from showing something it shouldn’t.

Not every third-party consumer has been tested, and some of them cache embed results or strip iframes. If someone tells you the embed isn’t appearing on their site, ask whether their platform allows embedded frames at all before you debug your own.

A pre-ship checklist for embeds

Before you publish a docs section or open a forum, run through this.

  1. Open each embedded paste while logged out, in a private window. See the code, and readers will too.
  2. Check the visibility of every paste you reference from a public page. Public is the safe choice. Unlisted works, but its link is visible in the page.
  3. Scan your embeds for burn-after-read pastes. They won’t appear through the URL route, and a locked card is not what you want in a tutorial.
  4. Hunt for passwords too, since a reader hitting a locked card in the middle of a how-to will leave.
  5. Check expiry dates on anything you embed. Expiry in a week will leave a hole in a page you meant to keep for years. Documentation should use no expiry.
  6. View the page at phone width. Frames have a fixed pixel width up to 800, so check that your theme lets it shrink or scroll rather than pushing the page sideways.
  7. Decide who owns the paste, and keep documentation snippets under a shared maintainer account rather than one person’s login.

Where this fits, and where it doesn’t

When code is the thing that changes, embeds are the right answer. They’re the wrong answer for a snippet you want to freeze at a point in time, such as a release note that should show exactly what shipped in one version. In that case, paste the code into the page as text, or embed a paste you promise never to edit.

Nor are they a replacement for access control. The visibility settings decide who can open a paste through your site. They are not encryption, and SnipShare doesn’t claim to be. Should a snippet hurt you in public, keep it out of any embed on a public page.

Weighing this against a hosted option? The Pastebin alternative page lays out what moves onto your own server. The practical difference for embeds is who controls the frame and the link: you do.

The short version

Pick the method that fits where the code will live. A bare URL covers the simple case in posts, pages, bbPress and BuddyPress. Use the shortcode when you need a file, a line range or a height cap. Embed public pastes on public pages, expect a plain link or a locked card when a paste can’t be shown, and run the checklist before you ship. One fix in one place replaces forty edits across your docs, and that’s the payoff.

For the wider picture of sharing code on your own domain, see the code snippet sharing overview.