Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/chrieke/mkdocs-exclude-search
🔎 A mkdocs plugin that excludes selected chapters from the docs search index.
https://github.com/chrieke/mkdocs-exclude-search
documentation mkdocs mkdocs-material mkdocs-plugin plugin search
Last synced: 2 months ago
JSON representation
🔎 A mkdocs plugin that excludes selected chapters from the docs search index.
- Host: GitHub
- URL: https://github.com/chrieke/mkdocs-exclude-search
- Owner: chrieke
- License: mit
- Created: 2020-10-11T23:10:29.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2023-12-04T02:34:50.000Z (about 1 year ago)
- Last Synced: 2024-09-30T07:43:24.254Z (3 months ago)
- Topics: documentation, mkdocs, mkdocs-material, mkdocs-plugin, plugin, search
- Language: Python
- Homepage:
- Size: 102 KB
- Stars: 27
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# mkdocs-exclude-search
A mkdocs plugin that excludes selected chapters from the docs 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.
## 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 `//filename.md` in the docs folder.
- Exclude specific heading subsections using the format `//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 `//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