Image Galleries (PhotoSwipe)
Relevant source files
The following files were used as context for generating this wiki page:
The Charlotte project utilizes the PhotoSwipe library to provide an interactive, full-screen image viewing experience (a "lightbox" or "gallery") for images embedded within Markdown content. When a user clicks on an image in a blog post, PhotoSwipe presents it in a responsive overlay, allowing for zooming, panning, and navigation between all images on the page.
This functionality is enabled through the photoswipe dependency and custom styling to integrate its appearance with the blog's theme. The initialization logic that binds PhotoSwipe to the images is not present in the analyzed files but is implicitly required for the feature to work.
Core Dependency
The project includes PhotoSwipe as a direct dependency. This provides the core JavaScript logic for the image gallery functionality.
| Dependency | Version |
|---|---|
photoswipe | ^5.4.4 |
Sources: package.json:34
Image Embedding
For an image to be part of the PhotoSwipe gallery, it must first be embedded into a post's Markdown content. Authors can use either standard Markdown syntax or raw HTML <img> tags. The system is designed to automatically detect these images and make them interactive.
Example Usage
Here is how images are added to posts, as demonstrated in the project's Markdown guide:
Markdown Syntax:
HTML Syntax:
<img src="/favicon/icon_256.webp" alt="头像图片" width="256" height="256" />
Sources: src/content/posts/2018-10-30/Charlotte-Markdown.md:73-79, src/content/posts/2018-10-30/Charlotte-Markdown.md:82-84
The post content schema also defines an image field in the frontmatter, which is used for the article's cover image but is generally not part of the inline PhotoSwipe gallery.
Sources: src/content/config.ts:8
User Interaction Flow
The following diagram illustrates the typical user flow when interacting with an image in a blog post, leading to the PhotoSwipe gallery view.
This diagram shows the inferred interaction, as the PhotoSwipe initialization script is not present in the provided files. The presence of photoswipe in package.json and the dedicated photoswipe.css file confirm this behavior.
Styling and UI Theming
The visual appearance of the PhotoSwipe gallery is controlled by src/styles/photoswipe.css. This file defines the layout, colors, and behavior of all UI components, such as buttons, the background overlay, and loading indicators. The styles are designed to be theme-aware, using CSS variables for colors.
Key UI Components
The stylesheet targets several core PhotoSwipe classes:
| CSS Class Selector | Description |
|---|---|
.pswp | The main wrapper and background overlay for the entire gallery. |
.pswp__button | Base class for all control buttons (e.g., close, arrows, zoom). |
.pswp__button--close | The "close" button. |
.pswp__button--arrow--prev, .pswp__button--arrow--next | The navigation arrows for moving between images. |
.pswp__button--zoom | The zoom-in/zoom-out toggle button. |
.pswp__counter | The text element that displays the current image index (e.g., "1 / 5"). |
.pswp__preloader | The loading spinner animation shown while an image is loading. |
Sources: src/styles/photoswipe.css
Theming with CSS Variables
The gallery's color scheme is customized using CSS variables, allowing it to adapt to the site's light and dark modes.
:root {
--pswp-bg: #000;
--pswp-icon-color: #fff;
--pswp-icon-color-secondary: #4f4f4f;
--pswp-icon-stroke-color: #000;
--pswp-icon-stroke-width: 2px;
--pswp-preloader-color: rgba(255, 255, 255, 0.6);
}
These variables control the background color, icon colors, and the preloader, ensuring a consistent look and feel with the rest of the Charlotte theme.
Sources: src/styles/photoswipe.css:2-9