← All posts

Share a Tutorial as One Paste With ZIP and Raw URLs

Publish a multi-file tutorial as one SnipShare paste. Readers get a ZIP of every file or a raw URL per file, with clear rules for private and locked pastes.

Five files in a tutorial do not need five links. Put the files in one SnipShare paste and the paste page gives your readers two ways to take the code away: a Download button that returns a ZIP of every file, and a Raw link on each file that returns that file as plain text. Those URLs also work from a terminal, so a reader can fetch one config file with curl and never open a browser.

This post is for the author who writes walkthroughs, workshop notes or setup guides and wants the code to travel with the text. Below: how the ZIP and the raw URLs behave, where they fail on purpose, and what to check on your host before you send readers to them.

One paste, several files

Pastes can hold several files. Every file gets its own name, its own language for syntax highlighting, and its own tab on the paste page. Think of a tutorial about a small plugin, carrying plugin.php, style.css, settings.json and a README, all in one place with one share link.

Two limits shape how you plan the set, and both are settings the site owner controls under SnipShare > Settings > General:

  • Max Files Per Paste defaults to 10, and the field accepts 1 to 50.
  • Total size comes from Max Paste Size, which counts the content of every file together, with a default of 100,000 bytes.

Go over either and the paste is refused with a message that names the limit, so a long tutorial may need splitting into two pastes. Filenames must also be unique inside a paste. Comparison ignores case and uses the stored name, because a ZIP or a case-insensitive disk would keep only one of two files that differ by capitals. Two files called Config.json and config.json get an error that says each file needs its own name.

Good news for authors: names are the handle readers use in raw URLs, so a paste where every name is distinct has an unambiguous address for every file.

What the Download button returns

On the paste page, the toolbar has a Download button next to Raw. What it returns depends on how many files the paste has.

  • One file: it downloads under its own name, as a generic binary download.
  • Several files: a ZIP arrives, containing every file under its stored filename.
  • The ZIP is named after the paste title, cleaned up into a safe filename, or after the share hash when the paste has no title.

So a title like “Build a contact form” is a better habit than leaving it blank. Your readers end up with a ZIP named for the tutorial instead of a string of letters and digits.

You can also link to it as a plain URL, /paste/<hash>/download/, once you swap in your paste’s hash: from your course page, a README, a newsletter. Default base is paste, and a site can change it with a filter, so check the actual link on your own paste page before you copy the pattern.

The ZIP needs a PHP extension

Building the ZIP needs PHP’s ZipArchive class on the server. With the extension missing, a multi-file download stops with the message “ZIP downloads require the ZipArchive PHP extension” and a 500 status. Single-file pastes are unaffected, because they never build an archive.

Most hosts ship the extension. Some trimmed images do not. Checking takes one minute and saves an embarrassing report from your first reader:

  1. Create a throwaway paste with two files.
  2. Open its page and press Download.
  3. Unpack the ZIP and confirm both files are inside with the names you gave them.

Do it on the live site, not a local copy, since the extension list belongs to the server. Should it fail, your host can enable the extension, and nothing in the paste needs to change.

One more detail worth knowing: the plugin writes the archive to the server’s temporary folder, streams it to the reader and deletes the temporary file afterwards. Tiny pastes make this cheap. Each download is still a request that builds a file, so a tutorial that goes viral deserves a look at your hosting limits.

The raw URL for each file

Every file on the paste page has its own Raw link next to the filename. Each points to /paste/<hash>/raw/<filename>, with the name URL-encoded, and returns the file’s content as plain text in UTF-8, with no page around it.

Put that link in a tutorial step. Wording such as “grab the starter file” can link straight to the raw address, and a terminal user can run:

curl -O https://example.com/paste/abc123/raw/settings.json

Domain, hash and filename in that line are placeholders, so copy the real link from your own paste. A name that matches no file in the paste gets a 404 with the text “File not found”.

Bare /paste/<hash>/raw/ serves every file at once, in order, as one text stream. When the paste has more than one file, each is preceded by a comment line that holds its name, starting with two slashes, and a blank line separates files. Whatever the file’s language, the separator stays the same, so a Python or shell file would carry a slash comment it does not understand.

In practice: use the per-file URL for anything that will be run or saved, and use the combined URL for reading.

The REST route, for tools

Pastes also have routes in the REST API, in the snipshare/v1 namespace. Three are relevant here:

  • Combined text: GET /pastes/<id>/raw.
  • One file, by its numeric file ID rather than its name: GET /pastes/<id>/raw/<file_id>.
  • The single file or the ZIP: GET /pastes/<id>/download.

These do not return the content inside a JSON body. All three answer with a 307 redirect to the canonical address above, so a client that follows redirects ends up on the same URL a browser would use. Same access rules as the web addresses apply, so a route cannot be used to read something the page would refuse.

For a tutorial author the useful point is a stable handle. Rename a file later and its raw name changes, but its numeric ID does not, which matters if you generate links in a script. An ID that is not in the paste returns a 404 with “File not found”.

Names decide the highlighting

When you add a file without picking a language, SnipShare works it out from the filename extension. A file called deploy.sh is highlighted as shell and settings.json as JSON, and a file created without a name falls back to untitled.txt. So name files the way your readers will save them. The name does three jobs at once: it sets the highlighting, it becomes the file’s name inside the ZIP, and it forms the last part of the raw URL.

Avoid names with spaces and odd punctuation. Filenames are cleaned with WordPress’s own filename sanitizer before they are stored, so a name like My Config.json is stored as My-Config.json. Pick the plain version yourself, and the name in your tutorial text will match the name in the ZIP.

A worked example, with placeholders

Say you publish a tutorial called “Build a contact form” with four files. Everything below is invented for illustration, including the domain and the hash.

  • form.php, the markup and the handler.
  • form.css, the styles.
  • form.js, the small script that submits it.
  • notes.txt, a plain list of what to change for your own site.

You set the paste public, give it the title “Build a contact form”, and save. The paste page shows four tabs, a Raw link beside each filename, and Raw and Download buttons in the toolbar. In your post you write the walkthrough and link each step: “copy form.css from the raw link” points to https://example.com/paste/abc123/raw/form.css. At the end, one line says “or download all four files” and links to https://example.com/paste/abc123/download/.

A reader who clicks the last link receives Build-a-contact-form.zip with the four files inside, exactly as named. Someone working in a terminal can fetch one file with curl and skip the rest. You wrote the tutorial once and kept one source of truth for the code.

Which pastes can be fetched

Raw and download share one access check, stricter than people expect. Rules, in the order that matters for a tutorial:

  • Public pastes work for anyone.
  • Unlisted pastes work for anyone who has the link. Since the link carries the hash, the raw and download URLs work without a login.
  • Private pastes answer “not found” to everyone except the author and moderators. Readers following your raw link get a 404, so a private paste is the wrong home for a tutorial.
  • Password-protected pastes refuse raw and download with a 403 until the visitor has unlocked the paste in that session, and an unlock lasts one hour. Curl cannot pass that check, so readers cannot script a locked tutorial.
  • Burn-after-read pastes refuse both, with a message to open the link to reveal the paste. Raw and download never reveal a burn paste; only the paste page can.

Expired pastes return 410 with “This paste has expired”. Responses for protected pastes carry no-cache headers, so a page cache or proxy is told not to keep them.

For a public tutorial, choose public or unlisted. Use unlisted when you want the link to circulate in a newsletter or a course without the paste appearing in archives. Our public paste site post covers what an open library needs around it, and that matters for the public case.

Putting it together on a tutorial page

Try this pattern, built only from the pieces above:

  1. Write the tutorial text in your normal post or docs page.
  2. Put all the code in one paste, with descriptive filenames and a title that reads like the tutorial.
  3. Set visibility to public or unlisted.
  4. In the post, link each step to the per-file raw URL, and add one Download all link to the /download/ address.
  5. Embed the paste for readers who want to see the code in place. Our embed post covers that.
  6. Test every link from a private browser window, because your own login can hide a permission problem.

Step 6 catches the common mistake. An author who is logged in can open a private paste, an expired one or a locked one, so everything looks fine. Logged-out readers get a 404.

One caution about shell snippets. Telling readers to pipe a raw URL into a shell asks them to run whatever the URL serves at that moment, and a paste can be edited later. Prefer wording like “download the file, read it, then run it”, and link the per-file address so they can review it.

Keeping the set consistent over time

Tutorials age. When a framework changes, one file in the set needs an update while the other four stay put. Editing the paste changes what the raw and download URLs return from then on, since they read the current files. Readers who open the page next month get the new version, which is usually what you want for fixes.

Cost: a ZIP someone downloaded last week is now out of date, and a tutorial that quotes line numbers will drift. A few habits help:

  • Mention in the tutorial text which version of the tool the code was written for.
  • Avoid line-number references to a paste you will edit.
  • Keep filenames stable, since renames break the raw links you have already published.
  • If a change is large, publish a new paste and link to it, instead of rewriting the old one.

Our earlier install walkthrough shows the same raw URLs from the owner’s side, with the first paste and the settings that matter on day one. Still deciding how the library fits your site? The code snippet sharing page lays out the pieces.

What to check before you publish

Here is a short checklist, in the order that saves the most embarrassment:

  • The paste is public or unlisted, with no password and no burn-after-read.
  • Every file has a distinct, descriptive name, and the title reads like the tutorial.
  • The combined size is well under the Max Paste Size.
  • Download returns a ZIP on the live site, with every file inside.
  • Each per-file raw link returns text, not an error page, from a logged-out window.
  • The tutorial text names the tool version and warns about running code from a URL.

Small on purpose, the whole feature comes down to one paste, one ZIP and one address per file. What remains is deciding what you want your readers to be able to do with it, and choosing visibility to match.