# mkdocs-image-gallery-plugin
MKDocs plugin to autogenerate a gallery based on a folder of images
## How to use this plugin?
Add this plugin to your mkdocs.yml configuration as follows:
``` yml
plugins:
- image-gallery:
image_folder: "./assets/images/gallery" # Folder in the docs directory containing images
separate_category_pages: false # Optional: Set to true to create separate pages for each category
youtube_links_file: "youtube-links.yaml" # Optional: Path (relative to docs/) for YouTube links
```
## Short Code Usage
Add these short codes to any markdown page in your docs to use the image gallery plugin.
Display Preview Gallery
`{{gallery_preview}}`
Display Full Gallery
`{{gallery_html}}`
Display Youtube Gallery
`{{youtube_gallery}}`
Simple.
## YouTube Video Gallery
Render a responsive YouTube video gallery from a YAML file in your `docs/` directory.
- **Shortcode**: place `{{youtube_gallery}}` anywhere in your Markdown.
- **Data source**: YAML file under `docs/` (default: `youtube-links.yaml`).
- **Playback**: Built‑in lightbox opens an embedded YouTube player on click.
### YAML formats (`docs/youtube-links.yaml`)
- Flat list of links:
```yaml
- https://www.youtube.com/watch?v=dQw4w9WgXcQ
- https://www.youtube.com/watch?v=ArOS-e2d-cM
```
- Categories mapping to lists of links:
```yaml
Rick Roll:
- https://www.youtube.com/watch?v=dQw4w9WgXcQ
IronMouse:
- https://www.youtube.com/watch?v=ArOS-e2d-cM
```
### Assets
The plugin automatically injects the required CSS and JS and copies them into the built site:
- CSS: `assets/stylesheets/image-gallery.css`
- JS: `assets/javascripts/youtube-gallery.js`
No extra configuration is needed beyond the plugin config below.
### Notes & limitations
- Works with standard YouTube URLs (`watch`, `youtu.be`, `embed`, `shorts`). Invalid links are skipped.
- No YouTube Data API usage; titles/metadata are not fetched.
### youtube_links_file
Path (relative to `docs_dir`) to the YAML file containing YouTube links. Supports either a flat list of links or a mapping of category names to lists of links.
- Default: `youtube-links.yaml`
## Add to Main Nav
Dont forget to add the page that contains your `{{gallery_html}}` short code to the main nav config in `mkdocs.yml` to have a link in the main navigation
Example:
```
nav:
- Gallery: gallery.md
```
## Configuration Options
### image_folder
The path to the folder containing your gallery images, relative to the docs directory. Each subfolder in this directory will be treated as a separate category.
### separate_category_pages
When set to `true`, the plugin will create separate pages for each category instead of displaying all categories on a single page. This is useful for large galleries with many images.
- Default: `false`
- When enabled:
- The main gallery page will show a list of categories with links to individual category pages
- Each category will have its own page with all images from that category
- The gallery preview will link directly to these separate category pages
### youtube_links_file
Path to your youtube links `youtube-links.yaml`.
## Notes
This plugin requires `glightbox` plugin to display clicked images in a lightbox.
`pip install mkdocs-glightbox`
### MkDocs Serve Compatibility
When using `mkdocs serve` with `separate_category_pages: true`, the plugin avoids regenerating category pages if they already exist. This prevents endless rebuild loops that could occur when the file watcher detects newly generated files.
## Server URLs
Offline plugin causes .html in the gallery urls. This plugin supports both server urls and offline urls.
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-image-gallery-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mkdocs, image, gallery",
"author": "APinchofDill",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/7b/30/6e57e50667d0661121e97974d100727e6e24191c41c60e58542ad0349473/mkdocs_image_gallery_plugin-1.3.0.tar.gz",
"platform": null,
"description": "# mkdocs-image-gallery-plugin\r\nMKDocs plugin to autogenerate a gallery based on a folder of images\r\n\r\n## How to use this plugin?\r\n\r\nAdd this plugin to your mkdocs.yml configuration as follows:\r\n\r\n``` yml\r\nplugins:\r\n - image-gallery:\r\n image_folder: \"./assets/images/gallery\" # Folder in the docs directory containing images\r\n separate_category_pages: false # Optional: Set to true to create separate pages for each category\r\n youtube_links_file: \"youtube-links.yaml\" # Optional: Path (relative to docs/) for YouTube links\r\n```\r\n\r\n## Short Code Usage\r\n\r\nAdd these short codes to any markdown page in your docs to use the image gallery plugin.\r\n\r\nDisplay Preview Gallery\r\n`{{gallery_preview}}`\r\n\r\nDisplay Full Gallery\r\n`{{gallery_html}}`\r\n\r\nDisplay Youtube Gallery\r\n`{{youtube_gallery}}`\r\n\r\nSimple.\r\n\r\n## YouTube Video Gallery\r\n\r\nRender a responsive YouTube video gallery from a YAML file in your `docs/` directory.\r\n\r\n- **Shortcode**: place `{{youtube_gallery}}` anywhere in your Markdown.\r\n- **Data source**: YAML file under `docs/` (default: `youtube-links.yaml`).\r\n- **Playback**: Built\u2011in lightbox opens an embedded YouTube player on click.\r\n\r\n### YAML formats (`docs/youtube-links.yaml`)\r\n\r\n- Flat list of links:\r\n\r\n```yaml\r\n- https://www.youtube.com/watch?v=dQw4w9WgXcQ\r\n- https://www.youtube.com/watch?v=ArOS-e2d-cM\r\n```\r\n\r\n- Categories mapping to lists of links:\r\n\r\n```yaml\r\nRick Roll:\r\n- https://www.youtube.com/watch?v=dQw4w9WgXcQ\r\nIronMouse:\r\n- https://www.youtube.com/watch?v=ArOS-e2d-cM\r\n```\r\n\r\n### Assets\r\n\r\nThe plugin automatically injects the required CSS and JS and copies them into the built site:\r\n\r\n- CSS: `assets/stylesheets/image-gallery.css`\r\n- JS: `assets/javascripts/youtube-gallery.js`\r\n\r\nNo extra configuration is needed beyond the plugin config below.\r\n\r\n### Notes & limitations\r\n\r\n- Works with standard YouTube URLs (`watch`, `youtu.be`, `embed`, `shorts`). Invalid links are skipped.\r\n- No YouTube Data API usage; titles/metadata are not fetched.\r\n\r\n### youtube_links_file\r\nPath (relative to `docs_dir`) to the YAML file containing YouTube links. Supports either a flat list of links or a mapping of category names to lists of links.\r\n\r\n- Default: `youtube-links.yaml`\r\n\r\n## Add to Main Nav\r\n\r\nDont forget to add the page that contains your `{{gallery_html}}` short code to the main nav config in `mkdocs.yml` to have a link in the main navigation\r\n\r\nExample:\r\n\r\n```\r\nnav:\r\n - Gallery: gallery.md\r\n```\r\n\r\n## Configuration Options\r\n\r\n### image_folder\r\nThe path to the folder containing your gallery images, relative to the docs directory. Each subfolder in this directory will be treated as a separate category.\r\n\r\n### separate_category_pages\r\nWhen set to `true`, the plugin will create separate pages for each category instead of displaying all categories on a single page. This is useful for large galleries with many images.\r\n\r\n- Default: `false`\r\n- When enabled:\r\n - The main gallery page will show a list of categories with links to individual category pages\r\n - Each category will have its own page with all images from that category\r\n - The gallery preview will link directly to these separate category pages\r\n\r\n### youtube_links_file\r\nPath to your youtube links `youtube-links.yaml`.\r\n\r\n## Notes\r\n\r\nThis plugin requires `glightbox` plugin to display clicked images in a lightbox.\r\n\r\n`pip install mkdocs-glightbox`\r\n\r\n### MkDocs Serve Compatibility\r\n\r\nWhen using `mkdocs serve` with `separate_category_pages: true`, the plugin avoids regenerating category pages if they already exist. This prevents endless rebuild loops that could occur when the file watcher detects newly generated files.\r\n\r\n## Server URLs\r\n\r\nOffline plugin causes .html in the gallery urls. This plugin supports both server urls and offline urls.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "An MkDocs plugin to generate an image gallery from a folder of images",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/APinchofDill/mkdocs-image-gallery-plugin"
},
"split_keywords": [
"mkdocs",
" image",
" gallery"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "07be01c51e1be5fe81001bfa83ee14d5afcc676a770154a3293f59d282acc10f",
"md5": "d8d08e194e2d6dc9ebc6d96d7a88606a",
"sha256": "67e1ba23ac3842c397b905a1b6f3b0e96b9824039d047621d507d59c8180937b"
},
"downloads": -1,
"filename": "mkdocs_image_gallery_plugin-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8d08e194e2d6dc9ebc6d96d7a88606a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16535,
"upload_time": "2025-08-19T02:26:22",
"upload_time_iso_8601": "2025-08-19T02:26:22.177945Z",
"url": "https://files.pythonhosted.org/packages/07/be/01c51e1be5fe81001bfa83ee14d5afcc676a770154a3293f59d282acc10f/mkdocs_image_gallery_plugin-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7b306e57e50667d0661121e97974d100727e6e24191c41c60e58542ad0349473",
"md5": "8db22c4382977cc98090229269da120c",
"sha256": "53fc49699033c4047524ac52e76c1bf6809f76f58d1de522dffb7e0e9da9e1a9"
},
"downloads": -1,
"filename": "mkdocs_image_gallery_plugin-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "8db22c4382977cc98090229269da120c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14868,
"upload_time": "2025-08-19T02:26:23",
"upload_time_iso_8601": "2025-08-19T02:26:23.007931Z",
"url": "https://files.pythonhosted.org/packages/7b/30/6e57e50667d0661121e97974d100727e6e24191c41c60e58542ad0349473/mkdocs_image_gallery_plugin-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 02:26:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "APinchofDill",
"github_project": "mkdocs-image-gallery-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mkdocs-image-gallery-plugin"
}
JSON
