Resource Library 1.0 · Install guide

Your downloads, guides and videos, in one place people can search.

Resource Library turns a Squarespace blog into a library of policies, forms, study guides, recorded training and links, with topic chips, a type and an audience filter, search, and a download button on every card. You write one blog post per resource and the library does the rest. Setting it up takes about ten minutes plus however long it takes to tidy your posts, and there’s nothing to install beyond one paste.

Before you start

• A Squarespace plan that runs JavaScript, which means Core, Plus or Advanced on the current plans, or Business, Commerce Basic or Commerce Advanced on older ones. The Basic and Personal plans don’t run custom scripts, so the library can’t work there.
• A blog that holds your resources, one post per resource. If you don’t have one yet, add a blog page called “Resources” and keep it out of your navigation if you like. The blog has to be public.
• Squarespace 7.0 or 7.1. Both work.

Install

1. Find your blog’s address. Open the resources blog on your live site and look at the address bar. If it reads yoursite.org/resources, the part you need is /resources.
2. Choose the page the library will live on. I’d suggest a new page called “Resources” in your navigation, with the blog itself hidden from the navigation (it still holds each resource’s own page). If you’d rather show the library on the blog’s own address, that works too, but a separate page gives you a heading and an introduction above it.
3. Edit the page, add a block and choose Code. Leave the mode on HTML and switch “Display source” off.
4. Open paste-into-code-block.html from this download in any text editor (TextEdit or Notepad are fine), copy everything and paste it into the Code block.
5. Near the top of what you pasted you’ll see data-source="/resources". Change /resources to your blog’s address from step 1.
6. On Squarespace 7.1, drag the Code block’s handles so it spans the full width of the section. On 7.0 it fills the column it sits in.
7. Save, and look at the live page in a private window. Squarespace doesn’t run scripts inside the editor, so you’ll see an empty block while editing.

Setting up your resources

Every post in the blog is one resource. The library reads what’s already there, so a blog you’ve been using for a while will mostly just work. Here’s exactly what it reads and how.

Title, picture and summary

The post’s title is the resource’s name and its thumbnail image is the card’s picture. Posts without a thumbnail get a placeholder drawn in your site’s accent colour with a symbol for the type (a page for a PDF, a play button for a video, and so on), so you don’t need a picture for everything. The summary on the card is the post’s excerpt. If a post has no excerpt, the library uses the first proper paragraph of the post instead, so it’s worth writing an excerpt when the first paragraph isn’t a good description.

Topics

Categories become topics, and so do ordinary tags. A post in the category “Safeguarding” with the tag “Youth” shows under both chips. Spelling and capitals don’t split a topic, so a “youth” tag and a “Youth” category end up together under the first spelling the library finds.

If your tags also do other jobs (“needs review”, “2024 archive”), write the topics you want as Topic: Safeguarding instead. As soon as any post has a Topic: tag, the library takes your plain tags to be housekeeping, and from then on only categories and Topic: tags become chips. The setup check says when it has done this.

Audiences and types

Tags that start with a label do something specific:

Write the label with a colon, as above. A dash works too if it has a space on each side (Type – Guide), so everyday tags like “Type-2 diabetes” or “For-profit partners” stay ordinary tags. The audience filter only appears once at least one post has an audience, and the type filter appears when there’s more than one type.

The button on each card

Each card has a main button and a Details link to the post. The library chooses the main button’s link by looking through the post in this order and taking the first it finds:

1. A file uploaded to Squarespace (its address starts with /s/), or any link ending in a document, audio, video or zip extension, such as .pdf, .docx, .xlsx, .pptx, .mp3, .mp4 or .zip. A Squarespace audio block counts too.
2. A Google Docs, Sheets, Slides or Drive link, or a Dropbox, OneDrive, SharePoint or Box link.
3. A YouTube or Vimeo video embedded in the post, or a video uploaded to Squarespace (that one plays on the post itself). Playlists, live streams and unlisted Vimeo videos open the right page too.
4. The first link to another website. Share buttons and email links are skipped.
5. If there’s nothing, the post itself.

The type comes from that link, unless a Type: tag says otherwise: PDF, Word, Document (Google Docs and other text files), Slides, Spreadsheet, Audio, Video, ZIP, Image, File, Link or Page. The button says what will happen, such as “Download PDF”, “Open spreadsheet”, “Open in Google Drive”, “Watch video” or “Open link”. Documents on your own site download straight away, recordings open in a new tab to play, and anything on another site opens in a new tab.

When a post links two to four files, the card shows “3 files” beside the date, and that opens a list of every file in the post. When a post links five or more, the main button itself says “See all 6 files” and opens the list, because downloading whichever file happens to come first wouldn’t help anyone. A pack like that takes its type from what most of its files are.

One more thing the library watches for: if the same link to another website appears in at least five posts and in 40% of them or more (a donate button or a newsletter sign-up in your post template, say), it’s treated as part of the template and skipped when choosing each resource’s link, unless it’s the only link a post has. Files and documents are never skipped like this, because it’s normal for several resources to share one handbook or one Drive folder. The setup check tells you when it has done this.

Featured and New

Give up to three resources the category or tag “Featured” and they show as large cards at the top of the library, the newest first. They’re left out of the grid underneath so nothing appears twice, and the row steps aside while someone is filtering or searching. Resources published in the last 30 days get a “New” badge. You can change both with the options below.

Run the setup check

Add ?lib=check to the end of your library page’s address, for example yoursite.org/resources-library?lib=check. A panel appears above the library showing how many resources it found, how many have a file or link, how many of each type, how many have a thumbnail, your topics and audiences, and how many are featured or new. Underneath is a short list of what to fix, in plain English, such as “7 resources have no file or link, so they open their own page.” Visitors never see this panel unless they type that address themselves.

Links people can share

Whatever someone has chosen is kept in the page address, so a filtered view can be shared or bookmarked. You can use these in your own buttons and emails too:

The browser’s Back button works the way people expect: choosing a topic on a card adds a step to the history, while changing the filters in the bar updates the address without filling the history up.

Options

Everything is set with attributes on the <div> line. You only need the ones you want to change.

A library that opens in list view on the safeguarding resources, with New badges for two weeks, looks like this:

<div data-resource-library data-source="/resources" data-view="list" data-start="topic/safeguarding" data-new-days="14"></div>

Changing the wording

Every label can be changed, which is handy for other languages or your own way of saying things. Put this in the Code block above the rest of the paste and change only the lines you want:

<script>
window.ResourceLibraryStrings = {
  search: 'Search our resources',
  all: 'Everything',
  allAudiences: 'Everyone',
  details: 'More info',
  isNew: 'Just added',
  actPdf: 'Get the PDF',
  typeWord: 'Document'
};
</script>

Labels with {n}, {total}, {q} or {count} in them fill in the number or the search for you. The type… labels name the types, the act… labels are the card buttons, and the verb… labels are the one-word buttons used on narrow cards. Here is every label with its default:

window.ResourceLibraryStrings = {
  search: 'Search the library',
  searchShort: 'Search',
  clear: 'Clear search',
  topics: 'Topics',
  all: 'All',
  type: 'Type',
  allTypes: 'All types',
  audience: 'Audience',
  allAudiences: 'All audiences',
  sort: 'Sort',
  newest: 'Newest',
  az: 'A–Z',
  best: 'Best match',
  view: 'View',
  grid: 'Grid',
  list: 'List',
  filters: 'Filters',
  close: 'Close',
  showN: 'Show {n}',
  clearAll: 'Clear all',
  featured: 'Featured',
  more: 'More resources',
  showMore: 'Show more',
  details: 'Details',
  isNew: 'New',
  files: '{n} files',
  filesIn: 'Files in this resource',
  openPage: 'Open the full page',
  newTab: '(opens in a new tab)',
  one: '{n} resource',
  many: '{n} resources',
  ofTotal: '{n} of {total} resources',
  forQuery: '{count} for “{q}”',
  loading: 'Loading the library',
  of: 'of',
  noResults: 'Nothing matches that. Try a broader word, or clear a filter.',
  gone: 'Nothing is filed under that any more.',
  none: 'There aren’t any resources here yet.',
  failed: 'The library couldn’t be loaded just now. Please refresh the page to try again.',
  someMissing: 'some older resources didn’t load, so refresh the page to try again',
  moreTopics: 'More topics',
  typePdf: 'PDF',
  typeWord: 'Word',
  typeDocument: 'Document',
  typeSlides: 'Slides',
  typeSpreadsheet: 'Spreadsheet',
  typeAudio: 'Audio',
  typeVideo: 'Video',
  typeImage: 'Image',
  typeZip: 'ZIP',
  typeFile: 'File',
  typeLink: 'Link',
  typePage: 'Page',
  actPdf: 'Download PDF',
  actWord: 'Download document',
  actGdoc: 'Open document',
  actSlides: 'Download slides',
  actGslides: 'Open slides',
  actSheet: 'Download spreadsheet',
  actGsheet: 'Open spreadsheet',
  actZip: 'Download ZIP',
  actImage: 'Download image',
  actFile: 'Download file',
  actAudio: 'Listen',
  actVideo: 'Watch video',
  actForm: 'Open form',
  actDrive: 'Open in Google Drive',
  actDropbox: 'Open in Dropbox',
  actOnedrive: 'Open in OneDrive',
  actSharepoint: 'Open in SharePoint',
  actBox: 'Open in Box',
  actFiles: 'See all {n} files',
  verbFiles: 'Files',
  actLink: 'Open link',
  actPage: 'Open page',
  verbDownload: 'Download',
  verbOpen: 'Open',
  verbWatch: 'Watch',
  verbListen: 'Listen',
  labelGdoc: 'Google Doc',
  labelGsheet: 'Google Sheet',
  labelGslides: 'Google Slides',
  labelForm: 'Form',
  labelDrive: 'Google Drive',
  labelDropbox: 'Dropbox',
  labelOnedrive: 'OneDrive',
  labelSharepoint: 'SharePoint',
  labelBox: 'Box'
};

Troubleshooting

The block is empty while I’m editing

That’s normal. Squarespace doesn’t run scripts in the editor. Check the live page in a private window.

“The library couldn’t be loaded”

Open the page with ?lib=check on the end and the panel will tell you why. It’s nearly always one of three things: data-source doesn’t match the blog’s address exactly, the blog is password protected or members-only, or the address points at a normal page instead of a blog.

A card opens the wrong link

The card uses the first file or link it finds in the order above. Move the right link higher in the post, or if the post is really a page to read, add the tag Type: Page and the card will open the post instead.

Too many topic chips

Every category and plain tag becomes a chip, most used first. The chips scroll sideways, so a long list still works, but if some tags are for your own housekeeping, either leave them out with data-ignore, or write the ones you do want as Topic: tags, which switches plain tags off as topics altogether.

The search bar hides under my header when I scroll

The library looks for anything pinned to the top of the window, including small floating buttons such as a menu or chat button, and sits below or beside it. That works on every template I’ve tested. If yours is different, email me the page address and I’ll take a look.

New resources don’t appear straight away

The library checks for changes on every visit with one quick request, and refreshes its copy when your blog changes. If a visitor’s browser blocks storage, it simply loads everything fresh each time.

Squarespace 7.0 with Ajax loading

Some 7.0 templates load pages without a full refresh. The library listens for that, but if it only appears after a reload, turn off Ajax loading under Design → Site Styles.

Updates and help

Updates for the 1.x versions are free. When one comes out you’ll get an email with the new files, and you replace the old paste with the new one. Your settings live on the <div> line, so keep that line.

If you get stuck, email kris@singhstudio.co.nz with your page address and what you’re seeing. It helps to include a screenshot of the ?lib=check panel.