Custom themes support

[rustoma]

Resolves: #62

Summary

Documentation updates and theme scaffolder fixes to improve the developer experience for contributors and theme creators.

Changes

Documentation

• Added missing command docs: create-theme
• Updated docs/themes.md with clearer instructions and development workflow
• Added Development section to main README with setup instructions
• Fixed command references and navigation throughout docs

Theme Scaffolder (spg create-theme)

• Fixed package imports (@simple-photo-gallery/common instead of @simple-photo-gallery/common/src/...)
• Removed monorepo-only TypeScript path mappings from generated themes
• Updated generated theme README with development instructions

Import Changes

• Switched from source imports (@simple-photo-gallery/common/src/gallery) to package entrypoint imports (@simple-photo-gallery/common)
• This aligns with the published package structure and works for external users

Important: Build common First

The common package must be built before TypeScript/ESLint can resolve @simple-photo-gallery/common imports. This is because:

• The package exports from dist/ (not src/)
• TypeScript/ESLint need the built declaration files to resolve types
• Added Development section to README with build instructions

After cloning the repo, run:

yarn install
yarn workspace @simple-photo-gallery/common build

This ensures proper type resolution and avoids "Cannot find module" errors.

Creating and Building Themes Locally

To create and test a theme during development:

From the gallery directory

cd gallery

Create a new theme

yarn gallery create-theme my-theme

Build a gallery with your theme (using local CLI)

yarn gallery build --theme ../themes/my-theme -g /path/to/gallery

This uses the local development CLI (yarn gallery) instead of the published spg command.

[haltakov]

So, while playing with these I have a suggestion how to make all commands and setting be more consistent...

The general rule should be that all theme settings (theme path, thumb size and thumb edge mode) should follow this hierarchy (which is partially implemented already):

CLI options > gallery.json config > default theme config > global defaults

Note that this is not the case for the theme param yet.

How this works across the different CLI commands:

1. init - we shouldn't ask things the user probably has no idea yet. Even more, we currently ask about the thumb size but no the theme. I suggest to leave it as before without asking, but allow the user to set --theme, --thumbnail-size and --thumbnail-edge that then stored in the gallery.json config. This is only for users that already know what they are doing with the theme
2. thumbnails - to be honest, I'm even thinking of removing this command as we can have just build. Not 100% sure yet. I suggest here we also allow the user to set --thumbnail-size and --thumbnail-edge if they want to
3. build - again, we allow the user to set --theme, --thumbnail-size and --thumbnail-edge which then take precedence over the gallery.json

[rustoma]

Changes introduced:

1. init - We do not ask users about themes or thumbnails here, but it is possible to set them using the --theme, --thumbnail-size, and --thumbnail-edge flags, which are then stored in the gallery.json config. The structure in gallery.json is flat. The theme is separate and thumbnails are separate. This gives flexibility and allows to set the thumbnail size independently without having to set the theme.
2. thumbnails - the --thumbnail-size and --thumbnail-edge flags have been added, but in fact this command seems unnecessary
3. build - we allow setting --theme, --thumbnail-size, and --thumbnail-edge - these are also set in gallery.json so that the theme has something to pull the configuration from later.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d3a8311eea

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Read gallery.json path from env in Astro build

This now reads import.meta.env.GALLERY_JSON_PATH, but the build only defines process.env.GALLERY_JSON_PATH in astro.config.ts. In Vite/Astro, import.meta.env only contains prefixed or explicitly defined vars, so this will be undefined during spg build, causing the code to fall back to ./gallery.json in the theme directory and loadGalleryData to throw when that file isn’t there. Use process.env.GALLERY_JSON_PATH here or add a Vite define for import.meta.env.GALLERY_JSON_PATH to avoid breaking CLI builds.

Useful? React with 👍 / 👎.