# mkdocs-exclude-search
A mkdocs plugin that lets you exclude selected files or sections from the search index.
If you only need to exclude a few pages or sections, mkdocs-material now introduced
[built-in search exclusion](https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-exclusion)!
The **mkdocs-exclude-search** plugin
[complements](https://squidfunk.github.io/mkdocs-material/blog/2021/09/26/excluding-content-from-search/#whats-new)
this with more configuration options (wildcard exclusions, ignoring excluded subsections). It also provides
search-exclusion functionality to regular mkdocs users.
<p align="center">
<img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/mkdocs-exclude-search">
<a href="https://pypi.org/project/mkdocs-exclude-search/" title="mkdocs-exclude-search on pypi"><img src="https://img.shields.io/pypi/v/mkdocs-exclude-search?color=brightgreen"></a>
<img src="./coverage.svg">
</p>
## Setup
Install the plugin using pip:
```bash
pip install mkdocs-exclude-search
```
**Activate the `search` and `exclude-search` plugins in `mkdocs.yml`**. `search` is required, otherwise
`exclude-search` has no effect!
```yaml
plugins:
- search
- exclude-search
```
More information about plugins in the [MkDocs documentation][mkdocs-plugins].
## Configuration
- List the markdown files to be excluded under `exclude` using the format `<path>/<to>/filename.md` in the docs folder.
- Exclude specific heading subsections using the format `<path>/<to>/filename.md#some-heading`. Chapter names are all lowercase, `-` as separator, no spaces.
- Exclude all markdown files within a directory (and its children) with `dirname/*`.
- Exclude all markdown files with a specific name within all subdirectories with `dirname/*/filename.md` or `/*/filename.md`.
- To still include a subsection of an excluded file, list the subsection heading under `ignore` using the format `<path>/<to>/filename.md#some-heading`.
- To exclude all unreferenced files (markdown files not listed in mkdocs.yml nav section), use `exclude_unreferenced: true`. Default false.
```yaml
plugins:
- search
- exclude-search:
exclude:
- first.md
- dir/second.md
- third.md#some-heading
- dir2/*
- /*/fifth.md
ignore:
- dir/second.md#some-heading
exclude_unreferenced: true
```
```yaml
nav:
- Home: index.md
- First chapter: first.md
- Second chapter: dir/second.md
- Third chapter: third.md
- Fourth chapter: dir2/fourth.md
- Fifth chapter: subdir/fifth.md
```
This example would exclude:
- the first chapter.
- the second chapter (but still include its `some-heading` section).
- the `some-heading` section of the third chapter.
- all markdown files within `dir2` (and its children directories).
- all markdown files named `fifth.md` within all subdirectories.
- all unreferenced files
## See Also
More information about templates [here][mkdocs-template].
More information about blocks [here][mkdocs-block].
[mkdocs-plugins]: http://www.mkdocs.org/user-guide/plugins/
[mkdocs-template]: https://www.mkdocs.org/user-guide/custom-themes/#template-variables
[mkdocs-block]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
Raw data
{
"_id": null,
"home_page": "https://github.com/chrieke/mkdocs-exclude-search",
"name": "mkdocs-exclude-search",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "mkdocs",
"author": "Christoph Rieke",
"author_email": "christoph.k.rieke@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1d/52/8243589d294cf6091c1145896915fe50feea0e91d64d843942d0175770c2/mkdocs-exclude-search-0.6.6.tar.gz",
"platform": null,
"description": "# mkdocs-exclude-search\n\nA mkdocs plugin that lets you exclude selected files or sections from the search index.\n\nIf you only need to exclude a few pages or sections, mkdocs-material now introduced \n[built-in search exclusion](https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-exclusion)! \nThe **mkdocs-exclude-search** plugin \n[complements](https://squidfunk.github.io/mkdocs-material/blog/2021/09/26/excluding-content-from-search/#whats-new) \nthis with more configuration options (wildcard exclusions, ignoring excluded subsections). It also provides \nsearch-exclusion functionality to regular mkdocs users.\n\n<p align=\"center\">\n <img alt=\"PyPI - Downloads\" src=\"https://img.shields.io/pypi/dm/mkdocs-exclude-search\">\n <a href=\"https://pypi.org/project/mkdocs-exclude-search/\" title=\"mkdocs-exclude-search on pypi\"><img src=\"https://img.shields.io/pypi/v/mkdocs-exclude-search?color=brightgreen\"></a>\n <img src=\"./coverage.svg\">\n</p>\n\n## Setup\n\nInstall the plugin using pip:\n\n```bash\npip install mkdocs-exclude-search\n```\n\n**Activate the `search` and `exclude-search` plugins in `mkdocs.yml`**. `search` is required, otherwise \n`exclude-search` has no effect!\n\n```yaml\nplugins:\n - search\n - exclude-search\n```\n\nMore information about plugins in the [MkDocs documentation][mkdocs-plugins].\n\n## Configuration\n\n- List the markdown files to be excluded under `exclude` using the format `<path>/<to>/filename.md` in the docs folder.\n- Exclude specific heading subsections using the format `<path>/<to>/filename.md#some-heading`. Chapter names are all lowercase, `-` as separator, no spaces.\n- Exclude all markdown files within a directory (and its children) with `dirname/*`.\n- Exclude all markdown files with a specific name within all subdirectories with `dirname/*/filename.md` or `/*/filename.md`. \n- To still include a subsection of an excluded file, list the subsection heading under `ignore` using the format `<path>/<to>/filename.md#some-heading`. \n- To exclude all unreferenced files (markdown files not listed in mkdocs.yml nav section), use `exclude_unreferenced: true`. Default false.\n\n```yaml\nplugins:\n - search\n - exclude-search:\n exclude:\n - first.md\n - dir/second.md\n - third.md#some-heading\n - dir2/*\n - /*/fifth.md\n ignore:\n - dir/second.md#some-heading\n exclude_unreferenced: true\n\n```\n```yaml\nnav:\n - Home: index.md\n - First chapter: first.md\n - Second chapter: dir/second.md\n - Third chapter: third.md\n - Fourth chapter: dir2/fourth.md\n - Fifth chapter: subdir/fifth.md\n```\n\nThis example would exclude:\n- the first chapter.\n- the second chapter (but still include its `some-heading` section).\n- the `some-heading` section of the third chapter.\n- all markdown files within `dir2` (and its children directories).\n- all markdown files named `fifth.md` within all subdirectories.\n- all unreferenced files\n\n## See Also\n\nMore information about templates [here][mkdocs-template].\n\nMore information about blocks [here][mkdocs-block].\n\n[mkdocs-plugins]: http://www.mkdocs.org/user-guide/plugins/\n[mkdocs-template]: https://www.mkdocs.org/user-guide/custom-themes/#template-variables\n[mkdocs-block]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A mkdocs plugin that lets you exclude selected files or sections from the search index.",
"version": "0.6.6",
"project_urls": {
"Homepage": "https://github.com/chrieke/mkdocs-exclude-search"
},
"split_keywords": [
"mkdocs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3bef9af45ffb1bdba684a0694922abae0bb771e9777aba005933f838b7f1bcea",
"md5": "38d8d6659f5638c29c410f56ef719aff",
"sha256": "2b4b941d1689808db533fe4a6afba75ce76c9bab8b21d4e31efc05fd8c4e0a4f"
},
"downloads": -1,
"filename": "mkdocs_exclude_search-0.6.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "38d8d6659f5638c29c410f56ef719aff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 7821,
"upload_time": "2023-12-03T22:58:19",
"upload_time_iso_8601": "2023-12-03T22:58:19.355318Z",
"url": "https://files.pythonhosted.org/packages/3b/ef/9af45ffb1bdba684a0694922abae0bb771e9777aba005933f838b7f1bcea/mkdocs_exclude_search-0.6.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1d528243589d294cf6091c1145896915fe50feea0e91d64d843942d0175770c2",
"md5": "88209092bb05d5be376cdc4229d2ff09",
"sha256": "3cdff1b9afdc1b227019cd1e124f401453235b92153d60c0e5e651a76be4f044"
},
"downloads": -1,
"filename": "mkdocs-exclude-search-0.6.6.tar.gz",
"has_sig": false,
"md5_digest": "88209092bb05d5be376cdc4229d2ff09",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 9501,
"upload_time": "2023-12-03T22:58:21",
"upload_time_iso_8601": "2023-12-03T22:58:21.259159Z",
"url": "https://files.pythonhosted.org/packages/1d/52/8243589d294cf6091c1145896915fe50feea0e91d64d843942d0175770c2/mkdocs-exclude-search-0.6.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-03 22:58:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chrieke",
"github_project": "mkdocs-exclude-search",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-exclude-search"
}
JSON
