Soño

An image gallery theme for Lume. See a live preview at https://koikurasu.github.io/sono/.

Detailed setup guides, manual configuration references, and troubleshooting are available in the wiki.

Features

• Spreadsheet-driven – Manage your entire gallery—images, dates, and custom metadata—from a single spreadsheet.
• Automatic image processing – Optimized thumbnails and lightbox images are generated at build time, no need to resize or optimize images separately.
• Highly customizable – Easily change the gallery layout, thumbnail size, and more via LumeCMS.
• Dynamic filtering – Custom metadata columns automatically become interactive filters, including a year range slider.
• PhotoSwipe lightbox – Click on any thumbnail to open the full image in a lightbox, with keyboard navigation, captions, zoom, and fullscreen support.
• Progressive enhancement – The gallery works without JavaScript, with hover captions and direct image links as fallbacks.
• Subgalleries – Easily create multiple gallery pages showing different subsets of your images.

Requirements

• Deno 2.x or later

Installation

There are two ways to get started:

Option A: Lume init command

# Initialize a new Lume site with the Soño theme
deno run -A https://lume.land/init.ts --theme=sono my-gallery

# Start the development server with live reload and LumeCMS
cd my-gallery
deno task serve

This initializes a new Lume site using the Soño theme with only the necessary configuration files. Updating to a new version of the theme can be done by running deno task lume upgrade.

Option B: Clone the full repository

# Clone the full repository into a new directory
git clone https://github.com/koikurasu/sono.git my-gallery

# Start the development server with live reload and LumeCMS
cd my-gallery
deno task serve

This downloads the full source code. If you don't have Git installed, you can download the archive instead. For users who want to use Soño as a base for a more customized site.

Getting started

1. Add your images

Place your images in src/assets/images/gallery/. Supported formats: jpeg, jp2, png, webp, gif, avif, heif and tiff.

2. Fill in the spreadsheet

Open src/_data/images.ods in LibreOffice Calc, Microsoft Excel, or any compatible spreadsheet program. Add a row for each image.

The reserved columns are:

Column	Required	Description
filename	Yes	Exact filename including extension, e.g. my-painting.jpg
date	No	Year (1665) or date (2021-05-30)
alt	No	Alt text for accessibility
caption	No	Caption shown in the lightbox. Supports Markdown, including links.

You can add any additional columns you like, which will be used to filter the gallery. See Custom metadata below.

3. Configure the theme

Your site's configuration is managed through a few key files:

• src/_data.json for site metadata (title, description, language) and gallery settings (layout style, image sizing, and output formats).
• src/_includes/sass/_gallery_variables.scss for gallery-specific dimensions and styling.
• src/_includes/sass/_theme_variables.scss for site-wide colors and typography.

The easiest way to configure your site is to use the LumeCMS interface. Start the development server (see step 4) and navigate to http://localhost:3000/admin. The CMS provides a user-friendly interface to edit all metadata, gallery settings, and CSS variables directly in your browser, with explanations for each option. For manual configuration details without the CMS and more advanced options, refer to the wiki.

4. Build or serve

# Development server with live reload and LumeCMS
deno task serve

# Production build
deno task build

Output goes to _site/. After configuring the site and adding images, build the production site using deno task build then upload the contents of the _site/ folder to your hosting provider. For more information about building and deploying sites with Lume see the Lume documentation.

Custom metadata

Add any columns to the spreadsheet beyond the reserved ones. Their names become data- attributes on each gallery item, which the filter system uses.

For multiple values in one column, separate them with commas. For example, a cell in a tags column might look like:

oil paint, portrait, 17th century

Date format

The date column accepts any date format, so long as the year is the only 4-digit number. It powers the year range slider filter.

Captions

Captions support Markdown inline formatting. To include a link, use standard Markdown syntax:

[Artist name](https://example.com)

If your URL contains parentheses, wrap it in angle brackets:

[Artist name](<https://commons.wikimedia.org/wiki/File:Example_(detail).jpg>)

Fonts

The theme ships with Aspekta (OFL 1.1). To use a different font, replace the files in src/assets/fonts/ and update the @font-face declarations in src/_includes/sass/_fonts.scss.

Credits and licensing

• Theme code released under the MIT license
• Aspekta font – SIL Open Font License 1.1
• PhotoSwipe – MIT
• Dynamic caption plugin for PhotoSwipe v5 – MIT
• Macy.js – MIT
• Akar Icons – MIT