Metadata-Version: 2.1
Name: mkdocs-exclude-unused-files
Version: 1.2.1
Summary: A mkdocs plugin that excludes assets that are unused (orphaned) from being included in the final mkdocs output.
Home-page: https://github.com/JonasDoesThings/mkdocs-exclude-unused-files
License: MIT
Keywords: mkdocs,mkdocs-plugin,unused-files,orphaned-files
Author: Jonas Lorenz
Author-email: jonas@jonasdoesthings.com
Requires-Python: >=3.8.1,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: beautifulsoup4 (>=4.12.2,<5.0.0)
Requires-Dist: mkdocs (>=1.4.3,<2.0.0)
Project-URL: Documentation, https://github.com/JonasDoesThings/mkdocs-exclude-unused-files/blob/main/README.md
Project-URL: History, https://github.com/JonasDoesThings/mkdocs-exclude-unused-files/releases
Project-URL: Issues, https://github.com/JonasDoesThings/mkdocs-exclude-unused-files/issues
Project-URL: Repository, https://github.com/JonasDoesThings/mkdocs-exclude-unused-files
Description-Content-Type: text/markdown

# 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

![pypi current version](https://img.shields.io/pypi/v/mkdocs-exclude-unused-files?style=flat-square)

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.                                                                                                |

