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! The mkdocs-exclude-search plugin complements 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:

pip install mkdocs-exclude-search

Activate the search and exclude-search plugins in mkdocs.yml. search is required, otherwise exclude-search has no effect!

plugins:
  - search
  - exclude-search

More information about plugins in the MkDocs documentation.

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.

Works with both the default use_directory_urls: true and use_directory_urls: false. The site index page (index.md) is always kept in the search index.

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

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.

More information about blocks here.