Publish your own site
This guide builds a viewer and dataset gallery from saved data, then publishes them on a static host. You will need the input data, a reviewed dataset configuration and access to the host. The Python package includes the viewer; publishing does not require editing its source code.
1. Install
python -m venv .venv && source .venv/bin/activate # or conda, uv, pipx
pip install spatialscape
spatialscape --versionWith the package and input files installed locally, you can build and preview a site offline. Remote inputs, reference downloads and deployment require network access.
2. Describe and build each dataset
Work inside your project folder:
mkdir -p spatialscape && cd spatialscape
spatialscape init ../analysis/spe_dlpfc.rds --id dlpfc --name "Human DLPFC" # writes ./dlpfc.yaml for review
# edit dlpfc.yaml: keep the annotations you want, name them, pick colors and the opening gene
spatialscape build dlpfc.yaml # -> bundles/dlpfc; validates itself, renders thumbnailsIf the site is going to GitHub Pages, put sharded: false at the top of each dataset yaml before the first build (Pages does not guarantee the Range requests sharded bundles need); build and site build then keep every rebuild unsharded.
init reads the object once and writes a yaml in which the likely annotations are already mapped and every other column is a comment, so most edits are deleting or uncommenting a line; see Writing dataset.yaml. Repeat for every dataset; each becomes a folder under bundles/. Rerun build after an edit to the dataset configuration. It rebuilds affected samples and updates the dataset metadata.
3. Look at it
spatialscape serve bundles --openThe local server serves the viewer, gallery and data from the same address. Check the annotations, images and gene colors before uploading. Links copied from this preview point to 127.0.0.1 and are local to the computer running the server.
4. Describe the gallery
A single dataset needs no more than spatialscape site build bundles -o site. For a gallery with a title, several datasets, paper links or "coming soon" cards, describe it in site.yaml:
spatialscape site init dlpfc.yaml other.yaml --title "Our lab's spatial data"title: Our lab's spatial data
intro: Published datasets, viewable in the browser without any installation.
nav: { title: Our lab, links: [{ label: Lab site, url: https://lab.example.org }] }
datasets:
- config: dlpfc.yaml # built into bundles/dlpfc when its data or yaml changed
paper: { title: Someone et al. 2026, url: https://doi.org/... }
tags: [cortex]
- config: other.yaml
- id: hippocampus # a "coming soon" card
name: Human hippocampus
platforms: [visium, snrnaseq]spatialscape site build site.yaml # -> site/: viewer, datasets.json, one folder per dataset
spatialscape serve site # same thing a visitor will seesite build builds any listed dataset whose data or yaml changed, then writes datasets.json from site.yaml and the bundles' manifests (names, counts, platforms, thumbnails). Edit site.yaml, never datasets.json. The gallery: site.yaml lists every key.
5. Deploy
site/ is a plain folder. Which host depends on the size of the bundles (du -sh site).
Under 1 GB: GitHub Pages, start to finish
Use this route when the complete site fits within the hosting limits. The bundles must be unsharded (sharded: false in each dataset yaml, see step 2). The site goes on its own branch of any repository, so your analysis repository can host it without mixing the two:
cd site
git init -b gh-pages && git add -A && git commit -m "spatialscape site"
git remote add origin git@github.com:YOURORG/YOURREPO.git
git push -u origin gh-pagesThen, once, on GitHub: Settings → Pages → Build and deployment → Source: Deploy from a branch → Branch: gh-pages, folder / (root). After the deployment completes, the site is at https://YOURORG.github.io/YOURREPO/; open it and run spatialscape validate https://YOURORG.github.io/YOURREPO/dlpfc. site build writes a .nojekyll file, so Pages serves the folder as is. To update: rebuild, then in site/ commit and push again.
Cloudflare Pages, Netlify and other static hosts can also serve the output folder. Check the host's current file-size and file-count limits, and verify HTTP Range support before uploading sharded bundles. See Hosting for the required headers and validation command.
Larger data: the site on Pages, the bundles on object storage
Keep the site small and put each bundle on a bucket, one bundle folder at a time (never bundles/ itself: its .cache/ sibling holds the converted R objects and is not meant to travel):
rclone copy bundles/dlpfc r2:my-bucket/dlpfc # or aws s3 sync bundles/dlpfc s3://my-bucket/dlpfc
spatialscape validate https://data.example.org/dlpfcThen add data_url: https://data.example.org to site.yaml and run site build again: the site carries only the viewer and the gallery's datasets.json (about 5 MB) and the data streams from the bucket. Hosting has the CORS policy each host needs, a copy-and-paste S3 + CloudFront setup, and what validate checks.
6. Share a view or export an image
View settings are stored in the URL. copy link in the viewer header gives a link that reopens the same gene, annotation, filters, camera and split. A link copied from spatialscape serve points at 127.0.0.1 and only opens on your computer (the button says so); links from the published site are the ones to send. PNG exports the frame with its legend for slides.
Changing things afterwards
Making changes lists, for every common edit, the yaml line and the command that applies it.
Updating later
- Anything in a dataset yaml or its source files:
spatialscape build <yaml>(orsite build site.yaml, which runs it for every listed dataset), then upload the bundle. - A new dataset:
initit, add aconfig:line tosite.yaml,site build, upload.