====== Gallery Plugin Usage Guide ======

===== Basic Syntax =====

==== Display All Images in a Namespace ====

The most common way is to specify a media namespace to display all images in that namespace:

<code>
{{gallery>:wiki:pagename?150x150&lightbox&showtitle}}
</code>

**Syntax Explanation:**
  * `:wiki:pagename` - Specify the media namespace (note: colon `:` must be in front of the namespace)
  * `150x150` - Thumbnail size (width x height, in pixels)
  * `lightbox` - Enable lightbox effect (click thumbnail to view full-size image)
  * `showtitle` - Show image title (if EXIF data is available)

==== Display a Single Image ====

You can also specify a single image file:

<code>
{{gallery>:wiki:pagename:imagename.jpg?150x150&lightbox}}
</code>

==== Manually Specify Image List ====

If you need to manually specify a list of images, use the following syntax:

<code>
<gallery 150x150&lightbox>
:wiki:pagename:image1.jpg
:wiki:pagename:image2.jpg
https://example.com/external_image.jpg
</gallery>
</code>

===== How to Upload Images =====

==== Step-by-Step Instructions ====

  * **Important Note**: Media files are shared across all language versions. You do NOT need to create separate folders for each language version. All language versions share the same image folder.
  * Click "Media Manager" in the navigation bar
  * In the left tree structure, click the root directory `[Root]` to expand
  * Find and expand the `wiki` folder (Note: not `en:wiki` or `zh:wiki`, but `wiki` under the root directory)
  * Find or create a folder named after your page (e.g., `新车间_xinchejian`) under the `wiki` folder
  * Click into that folder
  * Upload image files
  * Uploaded images will automatically appear in the gallery (both Chinese and English versions will display them)

==== Naming Conventions ====

  * Folder names should match the page name
  * For example: if the page is `en:wiki:xinchejian`, the media folder should be `wiki:新车间_xinchejian`
  * Image file names should use lowercase letters, numbers, and underscores; avoid spaces and special characters

===== Common Options =====

==== Size Settings ====

  * `150x150` - Thumbnail size (default)
  * `200x200` - Larger thumbnails
  * `100x100` - Smaller thumbnails
  * Note: Use lowercase `x`, e.g., `150x150`

==== Layout Options ====

  * `full` - Full-width responsive layout (default, recommended)
  * `center` - Center-aligned
  * `left` - Left-aligned
  * `right` - Right-aligned

==== Other Common Options ====

  * `lightbox` - Enable lightbox effect (enabled by default)
  * `nocrop` - Don't crop, maintain original image aspect ratio
  * `crop` - Crop thumbnails to match specified size
  * `showtitle` - Show image title
  * `showname` - Show filename
  * `nocache` - Disable caching (not recommended, only for debugging)

===== Complete Examples =====

==== Example 1: Basic Gallery ====

<code>
{{gallery>:wiki:新车间_xinchejian?150x150&lightbox&showtitle}}
</code>

Displays all images in the `wiki:新车间_xinchejian` namespace with 150x150 thumbnails, lightbox enabled, and titles shown.

==== Example 2: Custom Size and Layout ====

<code>
{{gallery>:wiki:pagename?200x200&center&nocrop&lightbox}}
</code>

Displays 200x200 thumbnails, center-aligned, no cropping, with lightbox enabled.

==== Example 3: Limit Number of Images ====

<code>
{{gallery>:wiki:pagename?150x150&=5&lightbox}}
</code>

Shows only the first 5 images.

===== Important Notes =====

  * Gallery output is cached by default. If you upload new images but they don't appear, you need to clear the page cache or wait for the cache to expire
  * Image files should be uploaded to the Media Manager, not the page directory
  * Media files are shared; all language versions share the same image folder
  * Recommended image formats: JPEG, PNG, or GIF
  * Image file names should follow valid DokuWiki page name format (lowercase letters, numbers, underscores)

===== Troubleshooting =====

==== Images Not Displaying ====

  * Check if images are uploaded to the correct media namespace
  * Check if the namespace path is correct (note: colon `:` must be in front of the namespace)
  * Clear page cache: add `&purge=true` to the page URL

==== Gallery Shows Empty ====

  * Confirm there are image files in the media namespace
  * Check if image file formats are supported (JPEG, PNG, GIF)
  * Check if file permissions are correct

==== Lightbox Not Working ====

  * Check if `lightbox` option is enabled
  * Clear browser cache
  * Check for JavaScript errors