# 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
```
## 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}}`
Simple.
## 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
## Features
### Lazy Loading with Skeleton Loaders
The gallery includes built-in lazy loading for all images, which improves page load performance. Images are loaded only when they come into view, and a smooth skeleton loader animation is displayed while images are loading.
### 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.
## The Future
More customization options coming.
## 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/cc/65/3c6d29fc2f48efbfe488577e3a7c50f0852af3d3ffa879d0ac88c31ecfaf/mkdocs_image_gallery_plugin-1.2.7.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```\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\nSimple.\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## Features\r\n\r\n### Lazy Loading with Skeleton Loaders\r\nThe gallery includes built-in lazy loading for all images, which improves page load performance. Images are loaded only when they come into view, and a smooth skeleton loader animation is displayed while images are loading.\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## The Future\r\n\r\nMore customization options coming.\r\n\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.2.7",
"project_urls": {
"Homepage": "https://github.com/APinchofDill/mkdocs-image-gallery-plugin"
},
"split_keywords": [
"mkdocs",
" image",
" gallery"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9ca87900c29e07fcf35cf99c8c077456ac3dc55d4c9c4ba591eb6cf96dac0130",
"md5": "dcf52c7de05b8974ab0e6b85fd521919",
"sha256": "5aece11f590c1e6897976775ba5cfb3f3ed91a3fae6418e0d24066aae8291cdd"
},
"downloads": -1,
"filename": "mkdocs_image_gallery_plugin-1.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dcf52c7de05b8974ab0e6b85fd521919",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9808,
"upload_time": "2025-07-28T03:54:32",
"upload_time_iso_8601": "2025-07-28T03:54:32.420530Z",
"url": "https://files.pythonhosted.org/packages/9c/a8/7900c29e07fcf35cf99c8c077456ac3dc55d4c9c4ba591eb6cf96dac0130/mkdocs_image_gallery_plugin-1.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cc653c6d29fc2f48efbfe488577e3a7c50f0852af3d3ffa879d0ac88c31ecfaf",
"md5": "176a1393dc022ea71e9281ab006f8c64",
"sha256": "b3be3706883d1654eb02275cba8f11eb79965c1cb73aa6ca474bfd972a1bd702"
},
"downloads": -1,
"filename": "mkdocs_image_gallery_plugin-1.2.7.tar.gz",
"has_sig": false,
"md5_digest": "176a1393dc022ea71e9281ab006f8c64",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9302,
"upload_time": "2025-07-28T03:54:33",
"upload_time_iso_8601": "2025-07-28T03:54:33.461353Z",
"url": "https://files.pythonhosted.org/packages/cc/65/3c6d29fc2f48efbfe488577e3a7c50f0852af3d3ffa879d0ac88c31ecfaf/mkdocs_image_gallery_plugin-1.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 03:54:33",
"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
