ScrollyBuilder

Control panel groups

The bottom controls are grouped by what you are trying to do, not by how Builder stores things.

• Workspace changes what you see while working.
• Drafts in Builder saves work in this browser so you can reopen it from the Draft Library.
• Backup Draft Files downloads or opens editable .builder.json project files.
• Publish Code creates finished HTML for Squarespace. Published code is not the editable draft.

Share Button

The Share Button creates a small reader-facing button for a published page. On supported devices it opens the native share sheet. If native sharing is unavailable, it copies the page link instead.

Using images

Squarespace image URLs

1. Upload the image to Squarespace or add it to any hidden/private page.
2. Open the image so you can see the image itself in the browser.
3. Copy the image address or URL.
4. Paste that URL into the Image URL field.

Best clue: the URL often ends with an image format such as .jpg, .png, or .webp, though Squarespace sometimes adds extra characters after it.

Using videos

Squarespace video URLs

1. Upload the video to Squarespace or use a hosted video file.
2. Find the direct video file URL, not just the page URL.
3. Paste the direct file URL into the Video URL field.

Best clue: direct video URLs often end with .mp4. YouTube/Vimeo page links usually need an embed module, not the Video Hero file field.

Advanced Options

Advanced Options shows fields for accessibility, data sources, reveal/highlight controls, and detailed chart settings.

Estimated Reading Time

Reading time is only an estimate. Most readers move through plain text at roughly 200–250 words per minute.

• Short essay: 600–1,000 words ≈ 3–5 minutes
• Typical essay: 1,200–1,800 words ≈ 5–9 minutes
• Long essay: 2,000–3,000 words ≈ 9–15 minutes

Scrolly stories are often experienced more slowly than plain articles because readers pause for images, charts, maps, and interactive elements. A useful rule of thumb is that visuals and interactions may increase engagement time beyond the word-count estimate.

Project status and next action

The project strip shows the current draft name, last saved time, project status, and next action. These fields are for re-entry: they help you remember what this piece needs when you come back later.

• Project status names where the piece is in the larger workflow: Idea Queue, Planning, Drafting, Designing / Display, Publishing, Published, or Paused.
• Next action should be plain and specific, such as “add Midrash rabbit hole,” “find hero image,” or “review accessibility.”
• Last saved updates when you use Save Draft, Save As, Download Draft, or download a draft backup from the library.

Draft files

Save Draft stores the current Builder project in this browser. Use this for quick local work.

Save As creates a separate local copy, useful before a major revision.

Download Draft saves a portable .builder.json file that you can keep in Dropbox, GitHub, or any project folder. This is the safest way to preserve work for later passes.

Open Draft loads a previously downloaded Builder draft file. Opening a file creates a new active draft so it will not overwrite an existing local draft unless you save it.

Draft Library lets you search local drafts, rename them, duplicate them, download a backup copy, or delete old drafts.

Copy Code, Download Code, and Save

• Copy Code copies the standalone HTML so you can paste it into a Squarespace code block.
• Download Code saves the same standalone HTML as a file.
• Save Draft stores a local draft in this browser only.

Layer Toggle Data Map help

What this module needs: a public GeoJSON file URL plus one or more numeric property fields inside that GeoJSON. The map draws the shapes from the GeoJSON, then colors those shapes using whichever field is selected as the active layer.

Good data sources to look for

• State and local open data portals: search for terms like Washington GeoJSON public health county, county boundaries GeoJSON, heat vulnerability GeoJSON, or ArcGIS REST GeoJSON.
• ArcGIS REST services: many government datasets can export as GeoJSON. Look for a layer URL that ends with /FeatureServer/0/query or /MapServer/0/query.
• GitHub raw GeoJSON files: use the raw file URL, not the normal GitHub preview page.

How to turn an ArcGIS layer into a GeoJSON URL

1. Open the public ArcGIS layer or REST service page.
2. Find the layer number, often something like FeatureServer/0.
3. Use a query URL like:
   ?where=1%3D1&outFields=*&f=geojson
4. The full URL usually looks like:
   https://.../FeatureServer/0/query?where=1%3D1&outFields=*&f=geojson
5. Paste that full URL into the Builder’s Dataset URL field.

What to put in each layer item

• Layer label: the short button text readers click, such as Heat, Income, or Housing.
• Field name: the exact property name in the GeoJSON, such as heat_index or poverty_pct. Field names are case-sensitive.
• Layer title/text: the narrative explanation that appears beside the map when that layer is active.
• Caption: optional note about interpretation, caveats, units, or source.

Common reasons a dataset will not load

• The URL is a webpage, not the raw GeoJSON data.
• The server blocks cross-site access, often called a CORS restriction.
• The file is too large for a smooth browser preview.
• The GeoJSON has no features array.
• The chosen field name does not exist in the GeoJSON properties.
• The chosen field is text instead of numeric data.

How to troubleshoot

1. Open the Dataset URL directly in a browser. If you do not see raw JSON text, Builder probably cannot load it.
2. Search the text for features. A GeoJSON FeatureCollection should have a features list.
3. Search for properties. The fields inside properties are the fields you can use as layers.
4. Copy field names exactly, including capitalization and underscores.
5. Start with one layer first. Once it works, add more layer items.

How to use the Layer Map well

Layer Map works best when each layer is a different lens on the same geography. Good layer sets might compare heat, income, race, asthma, tree canopy, flood risk, or access to care. The strongest narrative question is: What becomes visible when this layer turns on?

Accessibility fields

• Visual content → Alt Text
  Ask: “What does this image show?”
• Structure/experience → Accessibility Description
  Ask: “What is this module doing?” Especially important for Swap, Sticky, Rabbit Hole, Overlay, and other interactive or experiential modules.
• Meaning/interpretation → Diagram Description
  Ask: “What should someone understand from this chart or model?” Especially important for Bar, Pie, Bell, Loop, 2x2, Pyramid, Circles, and the IPCC Climate Model.