apenwarr / mkdocs-exclude Goto Github PK

A mkdocs plugin that lets you exclude files or trees from your output.

License: Apache License 2.0

Python 100.00%

mkdocs-exclude's Introduction

File exclude plugin for mkdocs

mkdocs-exclude is a mkdocs plugin that allows you to exclude files from your input using unix-style wildcards (globs) or regular expressions (regexes).

This implements what people were asking for in some mkdocs bugs, such as mkdocs/mkdocs#1500 and mkdocs/mkdocs#1152.

Quick start

Install the module using pip: pip3 install mkdocs-exclude

In your project, add a plugin configuration to mkdocs.yml:

plugins:
  - exclude:
      glob:
        - exclude/this/path/*
        - "*.tmp"
        - "*.pdf"
        - "*.gz"
      regex:
        - '.*\.(tmp|bin|tar)$'

You can provide zero or more patterns of each type. (If you don't provide any patterns, then nothing will happen!)

Note! Because of peculiarity of yaml syntax, the glob: and regex: lines must not start with a dash, but the lines under them must start with a dash.

Also because of yaml, patterns that start with a punctuation mark must be quoted.

When writing regexes, it's best to use single quotes rather than double quotes, so that your regex backslash escapes are preserved correctly without having to be doubled up.

mkdocs-exclude's People

Contributors

Stargazers

Watchers

Forkers

yurks balrok noisysundae posita nqkdev siphalor marcus-crane griperis nyaomidev shijubot

mkdocs-exclude's Issues

Separate the serve mode and the build mode

Thanks for this plugin. It's helpful for me.
I found this plugin to solve slow performance serve mode. It's works nicely.
Many files degrade serve mode performance.
It would be nice if I could separate the serve mode and the build mode.

Thanks.

PIP deprecation warning while installing Textual

Under Windows 10,

pip install "textual[dev]"

resulted in

DEPRECATION: mkdocs-exclude is being installed using the legacy 'setup.py install' method, because it does not have a 'pyproject.toml' and the 'wheel' package is not installed. pip 23.1 will enforce this behaviour change. A possible replacement is to enable the '--use-pep517' option. Discussion can be found at pypa/pip#8559

Thought you'd want to know...

include nav changes in the exclude filter?

Currently, the plugin correcly globs the directories that I want excluded from a build.
Would it also be possible to have it exclude those same patterns from the nav section?

For instance, say I have a yaml like so:

nav:
  path_a: 
    file1: path_a/file.md
    file2: path_a/file2.md
  path_b:
    file3: path_b/file.md
    file4: path_b/file2.md

with the associated exclude mapping

exclude:
  - glob:
      - path_b*

Then the plugin will correctly filter out the actual path items, but it will still leave the navigation menu intact.

Ideally any paths that also match the patterns in the nav section (and their parents, if they end up being empty) would also be removed.

This way we don't end up with a menu full of dangling links to files that don't exist.

Thanks for the plugin!

这个插件跟搜索功能有冲突，打开插件后搜索框就不显示了。

已经查到原因，所提问题不存在。

Using exclude plugin removes search

Hi!
I found this plugin great, but when including it it removes the search field from menu

With plugin:

without plugin:

Running: mkdocs -V
mkdocs, version 1.2.1 from ~/.local/lib/python3.8/site-packages/mkdocs (Python 3.8)

Thanks,
Matías.

Installation of mkdocs-exclue using poetry on Archlinux aarch64 (proot-distro) on Termux

I tried installing textual package with all its dev dependencies which includes mkdocs-exclude but when i did so it wasn't installed successfully.

How to reproduce this:

Install python poetry on your system ( note this prevails even if i used to install this package using pip)
Then,

poetry add "textual[dev]"

Which gave the following output for me:

Using version ^0.13.0 for textual

Updating dependencies
Resolving dependencies... Downloading https://files.pythonhosted.org/packages/44/e5/4fea13230bcebf24b28c0efd774a2dd65a0937a2d39e94a4503438b078ed/PyYAML-6.0-cp310-cp310-macosx_10_9_x86_64.whl (Resolving dependencies... Downloading https://files.pythonhosted.org/packages/64/08/2e192aa0a8e4741da0284559e983d22f02d12ca2cc18598948b99414c4b6/frozenlist-1.3.3-cp310-cp310-macosx_10_9_univerResolving dependencies... (21.3s)

Writing lock file

Package operations: 32 installs, 0 updates, 0 removals

  • Installing six (1.16.0)
  • Installing markupsafe (2.1.2)
  • Installing mdurl (0.1.2)
  • Installing python-dateutil (2.8.2)
  • Installing pyyaml (6.0)
  • Installing frozenlist (1.3.3)
  • Installing ghp-import (2.1.0)
  • Installing idna (3.4)
  • Installing jinja2 (3.1.2)
  • Installing markdown (3.3.7)
  • Installing markdown-it-py (2.2.0)
  • Installing mergedeep (1.3.4)
  • Installing multidict (6.0.4)
  • Installing pyyaml-env-tag (0.1)
  • Installing uc-micro-py (1.0.1)
  • Installing watchdog (2.3.1)
  • Installing aiosignal (1.3.1)
  • Installing async-timeout (4.0.2)
  • Installing attrs (22.2.0)
  • Installing charset-normalizer (3.1.0)
  • Installing linkify-it-py (2.0.0)
  • Installing mdit-py-plugins (0.3.5)
  • Installing mkdocs (1.4.2)
  • Installing pygments (2.14.0)
  • Installing yarl (1.8.2)
  • Installing zipp (3.15.0)
  • Installing aiohttp (3.8.4)
  • Installing importlib-metadata (4.13.0)
  • Installing mkdocs-exclude (1.0.2): Failed

  ChefBuildError

  Backend subprocess exited when trying to invoke build_wheel

  running bdist_wheel
  running build
  running build_py
  creating build
  creating build/lib
  creating build/lib/mkdocs_exclude
  copying mkdocs_exclude/__init__.py -> build/lib/mkdocs_exclude
  copying mkdocs_exclude/plugin.py -> build/lib/mkdocs_exclude
  installing to build/bdist.linux-aarch64/wheel
  running install
  running install_lib
  creating build/bdist.linux-aarch64
  creating build/bdist.linux-aarch64/wheel
  creating build/bdist.linux-aarch64/wheel/mkdocs_exclude
  copying build/lib/mkdocs_exclude/__init__.py -> build/bdist.linux-aarch64/wheel/mkdocs_exclude
  copying build/lib/mkdocs_exclude/plugin.py -> build/bdist.linux-aarch64/wheel/mkdocs_exclude
  running install_egg_info
  running egg_info
  writing mkdocs_exclude.egg-info/PKG-INFO
  writing dependency_links to mkdocs_exclude.egg-info/dependency_links.txt
  writing entry points to mkdocs_exclude.egg-info/entry_points.txt
  writing requirements to mkdocs_exclude.egg-info/requires.txt
  writing top-level names to mkdocs_exclude.egg-info/top_level.txt
  reading manifest file 'mkdocs_exclude.egg-info/SOURCES.txt'
  reading manifest template 'MANIFEST.in'
  adding license file 'LICENSE'
  writing manifest file 'mkdocs_exclude.egg-info/SOURCES.txt'
  Copying mkdocs_exclude.egg-info to build/bdist.linux-aarch64/wheel/mkdocs_exclude-1.0.2-py3.10.egg-info
  error: [Errno 13] Permission denied: 'build/bdist.linux-aarch64/wheel/mkdocs_exclude-1.0.2-py3.10.egg-info/requires.txt'


  at /usr/lib/python3.10/site-packages/poetry/installation/chef.py:152 in _prepare
      148│
      149│                 error = ChefBuildError("\n\n".join(message_parts))
      150│
      151│             if error is not None:
    → 152│                 raise error from None
      153│
      154│             return path
      155│
      156│     def _prepare_sdist(self, archive: Path, destination: Path | None = None) -> Path:

Note: This error originates from the build backend, and is likely not a problem with poetry but with mkdocs-exclude (1.0.2) not supporting PEP 517 builds. You can verify this by running 'pip wheel --use-pep517 "mkdocs-exclude (==1.0.2)"'.

  • Installing msgpack (1.0.5)
  • Installing rich (13.3.2)
(ERROR)-(Exit Code 1)-(General error)

Please help me with issue .
And I'm new to these stuffs.

Suggestions are welcomed.

Thank you.

Question: Possible to toggle excludes?

We have some content that we want to exclude only sometimes, e.g. when we build the docs for the "community edition" of our software. Other times, all docs shall be included. Files that we never want to include would just be completely removed from mkdocs.

Question: Is there a way to toggle the exclusion, e.g. via an environment variable, or switch?

Possible to include only some files?

I have a quite large page tree but only want to include a couple of md-Files. Is it possible to invert the patterns, i.E. only include some specific files and exclude everything else?

Plugin doesn't exclude folders

Hello, I am trying to exclude a virtual environment within a subfolder by this plugin, but it doesn't work. My project structure looks like:

├── docs
│   ├── index.md
│   ├── ingest
│   ├── qag
│   ├── search
│   └── theme
├── eapl_ingest
│   ├── app
│   ├── Dockerfile
│   ├── docs
│   ├── mkdocs.yml
│   ├── README.md
│   ├── requirements.txt
│   ├── site
│   ├── src
│   └── venv
├── eapl_qag
│   ├── app
│   ├── docker-compose.yml
│   ├── Dockerfile
│   ├── docs
│   ├── mkdocs.yml
│   ├── rabbitmq.conf
│   ├── README.md
│   ├── requirements.txt
│   ├── src
│   ├── tests
│   └── venv
├── eapl_search
│   ├── app
│   ├── Dockerfile
│   ├── docs
│   ├── mkdocs.yml
│   ├── README.md
│   ├── requirements.txt
│   └── src
├── mkdocs.yml
├── README.md
├── requirements.txt
└── venv
    ├── bin
    ├── etc
    ├── include
    ├── lib
    ├── lib64 -> lib
    ├── pyvenv.cfg
    └── share

I wish to exclude venv folder within eapl_ingest. Hence, in my parent folder's mkdocs file, I've mentioned:

plugins:
  - exclude:
      glob:
        - "eapl_ingest/venv/*"

But this isn't working. And as mkdocs is trying to load everything, I'm getting an error due to this virtual environment. Am I doing it correctly? If not, what should be done. Thanks!

How to override nav config so the exclude plugin works?

I have a scenario where in the mkdocs.yml, the nav is customized as per designed taxonomy. Now, we want to exclude some folders not to be rendered on the static site. For that, I used mkdocs-exclude and removed links under the "nav" in the mkdocs.yml. As the files are in docs directory and not under nav, it's throwing error.

Could someone please help me how to achieve desired goal?

Exclude the specific folders in the repo and remove some links from nav, so the static site renders only the desired content.

Thanks!

Forward slashes don't work under Windows

My MkDocs project runs on Windows, and forward slashes in path names don't work for me:

plugins:
  - exclude:
      glob:
        - "exclude/this/path/*"

This worked for me, but I guess it will only work on Windows:

plugins:
  - exclude:
      glob:
        - "exclude\\this\\path\\*"

Please fix this for cross-platform compatibility. We should be able to use forward slashes on all platforms, just like with other plugins.

Regex Issue: Use `search` instead of `match`

Is there a reason why re.match, which only matches If zero or more characters at the beginning of string match the regular expression pattern, is used instead of re.search, which looks at the entire string?

I have a case where I want to exclude all markdown files that have a certain folder name in its src_path, but can only get it to work when I change the below line in the plugin.

for r in regexes:
    if re.search(r, name):
        return False