# MkDocs Exclude Unused (orphaned) Files
A simple plugin for excluding files from being included in the mkdocs output if they are not referenced on other pages.
## Installation
Run `pip install --upgrade mkdocs-exclude-unused-files`
## Configuration
Basic Configuration in the `mkdocs.yml` file:
```yaml
plugins:
- exclude-unused-files:
file_types_to_check: ["png", "jpg", "jpeg", "gif"]
enabled: !ENV [CI, false]
```
This configuration will exclude all files from the final mkdocs output that has one of the configured file endings and are not referenced/linked to other pages.
### Default types
The plugin uses a default set of file types:
`png, jpg, jpeg, gif, pdf, ico, drawio, tif, tiff, zip, tar.gz, rar, ogg, mp3, mp4, vtt , ogv, mov, svg, pot, potx, ppsx, ppt, pptx, xlt, xltx, xls, xlsx, doc, docx, dot, dotx, vst, vstx, vsd, vsdx`
### All Configuration Options
| Setting | Default | Description |
|------------------------------|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| enabled | `True` | Whether the plugin is enabled when building your project. If you want to switch the plugin off, e.g. for local builds, use an [environment variables](https://www.mkdocs.org/user-guide/configuration/#environment-variables). |
| enabled_on_serve | `False` | Whether the plugin is enabled when serving your project. It does not apply if `enabled` is False. It's just to explicitly enable the plugin during mkdocs serve. |
| dry_run | `False` | Only print output into the command line and don't actually delete anything |
| silent | `False` | Don't print out the found orphan files in the build process |
| force_delete | `False` | By default the plugin only deletes files that are actually in the configured mkdocs output directory (site_dir). If you want to delete these files anyways due to your setup, enable this flag |
| file_types_to_check | `[]` | Only check these file types for their usage and delete them if necessary. |
| file_types_override_mode | `replace` | Behavior of `file_types_to_check` towards default types: `replace` - uses only defined types, `append` - adds additional types to default list, `remove` - removes specified types from default. |
| file_names_to_never_remove | `["favicon"]` | Files with these names will never get deleted, even if no usage is detected. |
| folders_to_never_remove_from | `["assets"]` | Files in these folders will never get deleted, even if no usage is detected. Useful for always including specific static files. |
| file_name_suffixes_to_trim | `["#only-light", "#only-dark"]` | Trim-away suffixes in this list when checking if a file-name is used. This is used for ignoring material-mkdoc's color-palette-toggle instructions (see [Issue-4](https://github.com/JonasDoesThings/mkdocs-exclude-unused-files/issues/4)). |
Raw data
{
"_id": null,
"home_page": "https://github.com/JonasDoesThings/mkdocs-exclude-unused-files",
"name": "mkdocs-exclude-unused-files",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<4.0",
"maintainer_email": "",
"keywords": "mkdocs,mkdocs-plugin,unused-files,orphaned-files",
"author": "Jonas Lorenz",
"author_email": "jonas@jonasdoesthings.com",
"download_url": "https://files.pythonhosted.org/packages/bf/98/052badf202f0b3966ae259c8c30891a4462a27fb0c72e5fcca9f6597249f/mkdocs_exclude_unused_files-1.3.0.tar.gz",
"platform": null,
"description": "# MkDocs Exclude Unused (orphaned) Files\n\nA simple plugin for excluding files from being included in the mkdocs output if they are not referenced on other pages.\n\n## Installation\n\n\n\nRun `pip install --upgrade mkdocs-exclude-unused-files`\n\n## Configuration\n\nBasic Configuration in the `mkdocs.yml` file:\n\n```yaml\nplugins:\n - exclude-unused-files:\n file_types_to_check: [\"png\", \"jpg\", \"jpeg\", \"gif\"]\n enabled: !ENV [CI, false]\n```\n\nThis configuration will exclude all files from the final mkdocs output that has one of the configured file endings and are not referenced/linked to other pages.\n\n### Default types\n\nThe plugin uses a default set of file types:\n\n`png, jpg, jpeg, gif, pdf, ico, drawio, tif, tiff, zip, tar.gz, rar, ogg, mp3, mp4, vtt , ogv, mov, svg, pot, potx, ppsx, ppt, pptx, xlt, xltx, xls, xlsx, doc, docx, dot, dotx, vst, vstx, vsd, vsdx`\n\n### All Configuration Options\n\n| Setting | Default | Description |\n|------------------------------|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| enabled | `True` | Whether the plugin is enabled when building your project. If you want to switch the plugin off, e.g. for local builds, use an [environment variables](https://www.mkdocs.org/user-guide/configuration/#environment-variables). |\n| enabled_on_serve | `False` | Whether the plugin is enabled when serving your project. It does not apply if `enabled` is False. It's just to explicitly enable the plugin during mkdocs serve. |\n| dry_run | `False` | Only print output into the command line and don't actually delete anything |\n| silent | `False` | Don't print out the found orphan files in the build process |\n| force_delete | `False` | By default the plugin only deletes files that are actually in the configured mkdocs output directory (site_dir). If you want to delete these files anyways due to your setup, enable this flag |\n| file_types_to_check | `[]` | Only check these file types for their usage and delete them if necessary. |\n| file_types_override_mode | `replace` | Behavior of `file_types_to_check` towards default types: `replace` - uses only defined types, `append` - adds additional types to default list, `remove` - removes specified types from default. |\n| file_names_to_never_remove | `[\"favicon\"]` | Files with these names will never get deleted, even if no usage is detected. |\n| folders_to_never_remove_from | `[\"assets\"]` | Files in these folders will never get deleted, even if no usage is detected. Useful for always including specific static files. |\n| file_name_suffixes_to_trim | `[\"#only-light\", \"#only-dark\"]` | Trim-away suffixes in this list when checking if a file-name is used. This is used for ignoring material-mkdoc's color-palette-toggle instructions (see [Issue-4](https://github.com/JonasDoesThings/mkdocs-exclude-unused-files/issues/4)). |\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A mkdocs plugin that excludes assets that are unused (orphaned) from being included in the final mkdocs output.",
"version": "1.3.0",
"project_urls": {
"Documentation": "https://github.com/JonasDoesThings/mkdocs-exclude-unused-files/blob/main/README.md",
"History": "https://github.com/JonasDoesThings/mkdocs-exclude-unused-files/releases",
"Homepage": "https://github.com/JonasDoesThings/mkdocs-exclude-unused-files",
"Issues": "https://github.com/JonasDoesThings/mkdocs-exclude-unused-files/issues",
"Repository": "https://github.com/JonasDoesThings/mkdocs-exclude-unused-files"
},
"split_keywords": [
"mkdocs",
"mkdocs-plugin",
"unused-files",
"orphaned-files"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3c4c6cc5f1c83c6484d1bd6e6bc9fbc40707eb7bba644eb3ce8bb71ecab38c32",
"md5": "7e8d3156826fc6103d394ec1649f4b95",
"sha256": "0d4982bf79f9b2dc00e6a5314343d7a863982f2ea014a0fef6fbc79f1f621662"
},
"downloads": -1,
"filename": "mkdocs_exclude_unused_files-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7e8d3156826fc6103d394ec1649f4b95",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<4.0",
"size": 6093,
"upload_time": "2024-01-27T19:49:03",
"upload_time_iso_8601": "2024-01-27T19:49:03.438384Z",
"url": "https://files.pythonhosted.org/packages/3c/4c/6cc5f1c83c6484d1bd6e6bc9fbc40707eb7bba644eb3ce8bb71ecab38c32/mkdocs_exclude_unused_files-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bf98052badf202f0b3966ae259c8c30891a4462a27fb0c72e5fcca9f6597249f",
"md5": "e76d08f8de4eeacb4a3c158e60a7159d",
"sha256": "f6eda2278f7b0059f4f63e0d9587334e106ab6861cf7b2879a1a1af7ae31e752"
},
"downloads": -1,
"filename": "mkdocs_exclude_unused_files-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "e76d08f8de4eeacb4a3c158e60a7159d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<4.0",
"size": 5424,
"upload_time": "2024-01-27T19:49:04",
"upload_time_iso_8601": "2024-01-27T19:49:04.766570Z",
"url": "https://files.pythonhosted.org/packages/bf/98/052badf202f0b3966ae259c8c30891a4462a27fb0c72e5fcca9f6597249f/mkdocs_exclude_unused_files-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-27 19:49:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JonasDoesThings",
"github_project": "mkdocs-exclude-unused-files",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-exclude-unused-files"
}
JSON
