### Install mkdocs-literate-nav

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

Install the plugin using pip. This is the initial step before activating it in your configuration.

```shell
pip install mkdocs-literate-nav
```

--------------------------------

### Programmatic Nav Generation Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

An example demonstrating how to programmatically generate both files and their corresponding navigation using mkdocs_gen_files.Nav.build_literate_nav.

```python
mkdocs_gen_files.Nav.build_literate_nav(
    globs=("**/*.py", "**/index.md")
)
```

--------------------------------

### Basic Plugin Setup

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/START_HERE.md

Configure the literate-nav plugin in your mkdocs.yml and define navigation in SUMMARY.md.

```yaml
# properdocs.yml
plugins:
  - literate-nav

# docs/SUMMARY.md
* [Home](index.md)
* [Guide](guide.md)
```

--------------------------------

### Wildcard Ordering Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

This example demonstrates how to control the ordering of navigation items when using wildcards. It shows how to prioritize directory entries over file entries.

```markdown
- */
- *
```

--------------------------------

### NavWithWildcards Structure Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/types.md

Shows an example of the NavWithWildcards structure, including literal paths, Wildcard objects, and DirectoryWildcard objects.

```python
[
    "index.md",
    {"API": [Wildcard("api/*.md")]},
    Wildcard("*.md"),
    DirectoryWildcard("docs/*/")
]
```

--------------------------------

### Nav Structure Example (After Resolution)

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/parser.md

Illustrates the final navigation structure after all wildcards have been resolved, compatible with ProperDocs.

```python
# Nav (after resolution)
[
    {"Home": "index.md"},
    {"API": ["api/client.md", "api/server.md"]},
    {"Changelog": "changelog.md"},
    {"Tutorial": ["tutorial/intro.md", "tutorial/advanced.md"]}
]
```

--------------------------------

### Wildcard Examples

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/parser.md

Demonstrates creating file and directory wildcards. `DirectoryWildcard` sets `trim_slash` to True.

```python
# File wildcard
wc = Wildcard("api", "*.md")
print(wc.value)  # "api/*.md"

# Directory wildcard
dwc = DirectoryWildcard("docs", "*/")
print(dwc.value)  # "docs/*"
print(dwc.trim_slash)  # True

```

--------------------------------

### Wildcard Usage Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/types.md

Shows how to instantiate the Wildcard class to match file patterns, including patterns with directory prefixes and parent references.

```python
from mkdocs_literate_nav.parser import Wildcard

# Match all markdown files in api directory
api_pattern = Wildcard("api", "*.md")
# value = "api/*.md"

# Match with parent directory reference
parent_pattern = Wildcard("..", "*.md")
# value = "../*.md"
```

--------------------------------

### RootStack Example Usage

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/types.md

Demonstrates the RootStack tuple format for tracking current and parent directories during recursive processing.

```python
("api/", ".")  # Processing api/ which is under root
("api/v2/", "api/", ".")  # Processing nested directory
```

--------------------------------

### Correct Plugin Ordering Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/configuration.md

Demonstrates the correct order for the literate-nav plugin in the plugins list to prevent conflicts with other plugins.

```yaml
plugins:
  - search
  - gen-files
  - literate-nav:      # Run after gen-files
      nav_file: SUMMARY.md
```

--------------------------------

### Example Implementation of get_nav_for_dir

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/types.md

Provides a sample implementation for the `get_nav_for_dir` callable, demonstrating how to find and read a 'SUMMARY.md' file within a given directory path.

```python
def get_nav_for_dir(path: str) -> tuple[str, str] | None:
    file = files.get_file_from_path(f"{path}/SUMMARY.md")
    if not file:
        return None
    content = Path(file.abs_src_path).read_text(encoding="utf-8-sig")
    return ("SUMMARY.md", content)
```

--------------------------------

### LiterateNav Plugin Configuration Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/plugin.md

Example of how to configure the literate-nav plugin in properdocs.yml, specifying options like nav_file, implicit_index, tab_length, and markdown_extensions.

```yaml
# properdocs.yml
plugins:
  - search
  - literate-nav:
      nav_file: SUMMARY.md
      implicit_index: false
      tab_length: 4
      markdown_extensions:
        - extra
        - toc
```

--------------------------------

### Implicit Index Example (Default)

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/configuration.md

Shows a SUMMARY.md structure where 'implicit_index' is false (default). The API section starts with explicit content, and index.md is not automatically included.

```markdown
# SUMMARY.md
* [Getting Started](intro.md)
* api/
```

--------------------------------

### Markdown Navigation Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

Define site navigation using Markdown lists. This example shows a simple structure with nested items.

```markdown
* [Frob](index.md)
* [Baz](baz.md)
* [Borgs](borgs/index.md)
    * [Bar](borgs/bar.md)
    * [Foo](borgs/foo.md)
```

--------------------------------

### NavWithWildcards Structure Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/parser.md

Illustrates the structure of a navigation list before wildcard resolution, potentially containing Wildcard objects.

```python
# NavWithWildcards (before resolution)
[
    {"Home": "index.md"},
    {"API": [Wildcard("api/*.md")]},
    Wildcard("*.md"),  # File wildcard
    DirectoryWildcard("*/")  # Directory wildcard
]
```

--------------------------------

### Directory Traversal Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/globber.md

Discover all immediate subdirectories within the project. This pattern is useful for iterating over top-level folders or specific directory structures.

```python
globber = MkDocsGlobber(files)

# Find all top-level directories
for path in globber.glob("*/"):
    print(f"Found directory: {path}")
```

--------------------------------

### ProperDocs Native Nav Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/docs/reference.md

Illustrates the structure of a `properdocs.yml` file when using native navigation, including wildcard and subdirectory cross-link items.

```yaml
nav:
- Foo: foo.md
- Usual:
    - usual/a.md
    - usual/b.md
- '*.md'
- Subdir: subdir/

```

--------------------------------

### Printing Resolved Navigation Structure

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

Example of how to resolve and print the navigation structure using `resolve_directories_in_nav` and `json.dumps` for debugging.

```python
import json
from mkdocs_literate_nav.plugin import resolve_directories_in_nav

nav = resolve_directories_in_nav(config.nav, files, "SUMMARY.md")
print(json.dumps(nav, indent=2))
```

--------------------------------

### Basic Plugin Configuration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/configuration.md

This is a basic example of how to configure the literate-nav plugin in your mkdocs.yml or properdocs.yml file. It specifies the name of the navigation file to be used.

```yaml
plugins:
  - literate-nav:
      nav_file: SUMMARY.md
      implicit_index: false
      tab_length: 4
      markdown_extensions: []
```

--------------------------------

### Migrating from GitBook: Plugin Configuration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

Configuration for properdocs.yml when migrating from GitBook, including essential plugins and the literate-nav setup.

```yaml
plugins:
  - search
  - same-dir
  - section-index
  - literate-nav:
      nav_file: SUMMARY.md
```

--------------------------------

### Configure Custom Navigation Filename

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/configuration.md

Example demonstrating how to use a custom filename for the navigation specification file instead of the default SUMMARY.md.

```yaml
plugins:
  - literate-nav:
      nav_file: NAV.md
```

--------------------------------

### Example Literate Nav File with Wildcards

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

This literate nav file demonstrates the use of wildcards to define navigation structure. It includes explicit links and wildcard patterns for directories and files.

```markdown
- [Welcome](index.md)
- Usage
    - [Foo](usage/foo.md)
    - usage/*.md
- */
- *.md
- [API docs](api/)
- [License](license.md)
```

--------------------------------

### Simple Literate Nav Structure

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/INDEX.md

A basic SUMMARY.md structure with top-level links to introduction, user guide, and API reference.

```markdown
# docs/SUMMARY.md
* [Introduction](index.md)
* [User Guide](guide/index.md)
* [API Reference](api/index.md)
```

--------------------------------

### Example Nav List Syntax

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/docs/reference.md

Demonstrates the structure of a navigation list in a Markdown file. It includes regular links, subsection titles with nested lists, and wildcard entries.

```markdown
* [First list item](some-page.md)
* Subsection title
    * [Something](subdirectory/something.md)
    * subdirectory/*.md
* [Other directory](other/)
```

--------------------------------

### Markdown Navigation File Syntax Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/START_HERE.md

Illustrates the syntax for creating navigation structures in Markdown files, including page links, section names, directory cross-links, and wildcard patterns.

```markdown
* [Page](file.md)              # Page link
* Section Name
    * [Sub page](sub.md)
* [Directory](api/)            # Cross-link to subdirectory
* api/*.md                     # Wildcard: all .md in api/
* */                           # Wildcard: all subdirectories
<!--nav-->                     # Explicit nav marker (optional)
```

--------------------------------

### Example Nav Structure

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/types.md

Illustrates a typical nested navigation structure after all processing. Elements can be file paths or dictionaries representing sections.

```python
# Example Nav structure
[
    "index.md",
    {
        "Getting Started": "guide/intro.md"
    },
    {
        "API Reference": [
            "api/client.md",
            "api/server.md",
            {
                "Advanced": "api/advanced/index.md"
            }
        ]
    }
]
```

--------------------------------

### DirectoryWildcard Usage Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/types.md

Demonstrates using DirectoryWildcard to match directory patterns. The trailing slash in the pattern indicates directory-only matching.

```python
from mkdocs_literate_nav.parser import DirectoryWildcard

# Match all subdirectories
all_dirs = DirectoryWildcard("tutorials", "*/")
# value = "tutorials/*"

# The trailing slash indicates directory-only matching
```

--------------------------------

### mkdocs-literate-nav Navigation File Syntax: Basic Entries

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

Example of creating a SUMMARY.md file using mkdocs-literate-nav syntax. It shows how to define pages, sections with sublists, directory cross-links, and wildcard patterns for files and directories.

```markdown
* [Home](index.md)                    # Page
* Getting Started                     # Section (needs sublist)
    * [Intro](intro.md)
    * [Setup](setup.md)
* [API](api/)                         # Directory cross-link
* api/*.md                            # Wildcard for all .md files in api/
* */                                  # All subdirectories
```

--------------------------------

### Direct Globber Usage Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/INDEX.md

Shows how to use the MkDocsGlobber class directly in Python to check for directory existence, find matching files using glob patterns, and locate index files.

```python
from mkdocs_literate_nav.plugin import MkDocsGlobber

globber = MkDocsGlobber(files)

# Check for directory
if globber.isdir("api"):
    print("API directory exists")

# Find matching files
for path in globber.glob("api/*.md"):
    print(path)

# Find index file
if idx := globber.find_index("tutorials"):
    print(f"Tutorial index: {idx}")
```

--------------------------------

### Subdirectory Cross-link Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/docs/reference.md

Shows how to include a subdirectory's navigation by linking to it with a trailing slash. This is equivalent to creating a subsection that includes all items from the target directory.

```markdown
* [Foo](foo/)
```

--------------------------------

### Example of Recursive Link Detection

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/errors.md

Illustrates a Markdown structure that could lead to recursion detection between two files.

```markdown
# docs/a/SUMMARY.md
* [Section A](a/)

# docs/a/SUMMARY.md
* [Back to root](../)
```

--------------------------------

### Direct Parser Usage Example

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/INDEX.md

Demonstrates how to use the NavParser class directly in Python for parsing navigation structures, including error handling for parse errors.

```python
from mkdocs_literate_nav.parser import NavParser
from mkdocs_literate_nav.plugin import MkDocsGlobber

# Create globber from files
globber = MkDocsGlobber(files)

# Create parser
parser = NavParser(
    get_nav_for_dir=my_get_nav_func,
    globber=globber,
    implicit_index=False,
    markdown_config={'extensions': []}
)

# Parse navigation
try:
    nav = parser.markdown_to_nav()
except LiterateNavParseError as e:
    print(f"Parse error: {e}")
```

--------------------------------

### Configure Tab Length for Indentation

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/configuration.md

Example of setting the 'tab_length' option to 2 spaces for parsing Markdown lists in navigation files, following modern conventions.

```yaml
plugins:
  - literate-nav:
      tab_length: 2
```

--------------------------------

### Custom Error Handling for Nav Parsing

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/errors.md

Demonstrates how to use `NavParser` directly and catch `LiterateNavParseError` for custom error handling during navigation file processing. Ensure proper setup of `MkDocsGlobber` and the parser.

```python
from mkdocs_literate_nav.parser import NavParser, LiterateNavParseError
from mkdocs_literate_nav.plugin import MkDocsGlobber

def process_nav_files(files, markdown_config):
    globber = MkDocsGlobber(files)
    
    def get_nav_for_dir(path: str):
        # Your implementation
        ...
    
    parser = NavParser(
        get_nav_for_dir,
        globber,
        markdown_config=markdown_config
    )
    
    try:
        nav = parser.markdown_to_nav()
    except LiterateNavParseError as e:
        # Handle parsing errors
        print(f"Error in nav file: {e}")
        raise  # Re-raise or provide fallback
    
    return nav

```

--------------------------------

### Catch LiterateNavError

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/errors.md

Example of catching the base LiterateNavError when parsing navigation.

```python
from mkdocs_literate_nav.exceptions import LiterateNavError

try:
    nav = parser.markdown_to_nav()
except LiterateNavError as e:
    print(f"Navigation error: {e}")
```

--------------------------------

### Initializing and Using MkDocsGlobber

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/globber.md

Demonstrates how to create an instance of MkDocsGlobber with a MkDocs Files collection and then use its methods to check if a path is a directory and to find files matching a pattern.

```python
from mkdocs_literate_nav.plugin import MkDocsGlobber

# Create globber from MkDocs files
globber = MkDocsGlobber(files)

# Globber is now ready for pattern matching
is_dir = globber.isdir("api")
matching_files = globber.glob("api/*.md")

```

--------------------------------

### Project Entry Point Configuration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/plugin.md

Configures the LiterateNavPlugin as an entry point in pyproject.toml for MkDocs to discover.

```toml
[project.entry-points."mkdocs.plugins"]
literate-nav = "mkdocs_literate_nav.plugin:LiterateNavPlugin"
```

--------------------------------

### Catch LiterateNavParseError

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/errors.md

Example of catching a specific LiterateNavParseError during navigation parsing. If caught, it prints the error and exits.

```python
from mkdocs_literate_nav.parser import LiterateNavParseError
from mkdocs_literate_nav.exceptions import LiterateNavError
import sys

try:
    nav = parser.markdown_to_nav()
except LiterateNavParseError as e:
    print(f"Parse error in nav file: {e}")
    # Include the error details in your build output
    sys.exit(1)
except LiterateNavError as e:
    print(f"Navigation error: {e}")
    sys.exit(1)
```

--------------------------------

### NavParser Initialization and Usage

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

This Python code demonstrates how to initialize the NavParser with a callback for directory navigation, a file globber, implicit index setting, and markdown configuration. It also shows methods for parsing markdown and resolving YAML navigation.

```python
parser = NavParser(
    get_nav_for_dir=callback,           # Returns (name, content) or None
    globber=MkDocsGlobber(files),       # File globber
    implicit_index=False,                # Auto-include index?
    markdown_config={'extensions': []}   # Markdown config
)

# Parse
nav = parser.markdown_to_nav()          # Markdown nav → Nav structure
nav = parser.resolve_yaml_nav(yaml)     # YAML nav → resolved nav
```

--------------------------------

### Initialize NavParser

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/parser.md

Instantiate the NavParser class. Use `implicit_index=True` to automatically include index files. `get_nav_for_dir` and `globber` are required dependencies.

```python
class NavParser:
    def __init__(
        self,
        get_nav_for_dir: Callable[[str], tuple[str, str] | None],
        globber: MkDocsGlobber,
        *,
        implicit_index: bool = False,
        markdown_config: dict | None = None,
    ):

```

--------------------------------

### GitHub-Friendly Configuration with Custom Nav File

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

Configuration for a GitHub-friendly project using literate-nav, setting the navigation file to README.md and adjusting tab length.

```yaml
# properdocs.yml
plugins:
  - literate-nav:
      nav_file: README.md
      tab_length: 2

# docs/README.md
# Navigation

* [Home](index.md)
* [Docs](docs/)

Rest of README content here...
```

--------------------------------

### Activate Plugin in properdocs.yml

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

Configure the plugin in your `properdocs.yml` file. Specify the `nav_file` if you are not using the default 'SUMMARY.md'.

```yaml
plugins:
  - search
  - literate-nav:
      nav_file: SUMMARY.md
```

--------------------------------

### Basic Navigation File Syntax

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/INDEX.md

Illustrates the fundamental syntax for defining site navigation using Markdown.

```markdown
* [Page Title](path/to/page.md)
* Section Title
    * [Subpage](subpage.md)
    * subsection/*.md
* [Directory Cross-Link](api/)
```

--------------------------------

### Large Project Configuration with API Docs

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

Configuration for a large project using literate-nav, enabling implicit index, and organizing API documentation with wildcards.

```yaml
# properdocs.yml
plugins:
  - literate-nav:
      implicit_index: true

# docs/SUMMARY.md
* [Home](index.md)
* Getting Started
    * [Installation](guide/install.md)
    * [Quickstart](guide/quickstart.md)
* User Guide
    * [guide/](guide/)
* [API Reference](api/)
* *.md

# docs/api/SUMMARY.md
* [Overview](index.md)
* api/*.md
```

--------------------------------

### Handling LiterateNavParseError

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/parser.md

Example of how to catch and handle a LiterateNavParseError during navigation parsing. The error message includes the problematic XML element for debugging.

```python
try:
    nav = parser.markdown_to_nav()
except LiterateNavParseError as e:
    print(f"Parse error: {e}")
    # Output includes the problematic XML element
```

--------------------------------

### MkDocsGlobber Constructor Initialization

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/globber.md

Illustrates the internal data structures built by the MkDocsGlobber constructor, including normalized file paths, directory paths, and mappings of directories to their index files.

```python
files = {
    PurePosixPath("/docs/index.md"): True,
    PurePosixPath("/docs/guide/intro.md"): True,
    PurePosixPath("/docs/api/client.md"): True,
}
dirs = {
    PurePosixPath("/"): True,
    PurePosixPath("/docs"): True,
    PurePosixPath("/docs/guide"): True,
    PurePosixPath("/docs/api"): True,
}
index_dirs = {
    PurePosixPath("/docs"): PurePosixPath("/docs/index.md"),
    PurePosixPath("/docs/guide"): PurePosixPath("/docs/guide/index.md"),
}

```

--------------------------------

### Accessing Plugin Configuration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/types.md

Demonstrates how to access the configuration attributes of a LiterateNavPlugin instance after it has been initialized.

```python
# Accessed via plugin instance
plugin = LiterateNavPlugin()
nav_file_name = plugin.config.nav_file  # "SUMMARY.md"
implicit = plugin.config.implicit_index  # False
tab_len = plugin.config.tab_length  # 4
```

--------------------------------

### Initialize MkDocsGlobber

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/plugin.md

Instantiate MkDocsGlobber with a MkDocs Files collection to enable file globbing and directory detection capabilities.

```python
class MkDocsGlobber:
    def __init__(self, files: Files):

```

--------------------------------

### Plugin Entry Point Registration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/INDEX.md

Specifies how the LiterateNavPlugin is registered with MkDocs.

```ini
mkdocs.plugins = "literate-nav = mkdocs_literate_nav.plugin:LiterateNavPlugin"
```

--------------------------------

### Hybrid Navigation Configuration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/configuration.md

Illustrates how to mix literate nav with ProperDocs' native YAML navigation, including wildcard expansion.

```yaml
nav:
  - Home: index.md
  - API: api/              # Defers to api/SUMMARY.md
  - Guides: guides/
  - '*'                    # Wildcard expands remaining files

plugins:
  - literate-nav:
      nav_file: SUMMARY.md
```

--------------------------------

### Full mkdocs-literate-nav Configuration Options

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

This configuration demonstrates all available options for the literate-nav plugin, including custom nav file names, implicit index behavior, tab length for indentation, and markdown extensions for parsing.

```yaml
plugins:
  - literate-nav:
      nav_file: SUMMARY.md           # Nav file name (per directory)
      implicit_index: false           # Auto-include index files?
      tab_length: 4                   # Markdown indent: 2 or 4 spaces
      markdown_extensions:            # Extensions for nav parsing
        - extra
```

--------------------------------

### Match Files for Inclusion

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/globber.md

Find all files matching a specific pattern, such as all markdown files in a 'tutorials' directory. Supports fallback logic if no files are found.

```python
globber = MkDocsGlobber(files)

# Find all tutorial files
tutorials = list(globber.glob("tutorials/*.md"))
if tutorials:
    nav_items = tutorials
else:
    # Fallback if no tutorials found
    nav_items = ["tutorials/"]
```

--------------------------------

### DirectoryWildcard Initialization

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/parser.md

Initializes a DirectoryWildcard to match all subdirectories within a given path. Used to distinguish between matching files and directories.

```python
# Match all subdirectories
dir_wc = DirectoryWildcard("tutorials", "*/")
# Matches tutorials/intro/, tutorials/advanced/, etc.
```

--------------------------------

### Correct Markdown with Link

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/errors.md

Demonstrates the correct Markdown syntax for a section title with a direct link.

```markdown
* [Section Title](section.md)
```

--------------------------------

### Docs Directory Configuration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/configuration.md

Shows how the plugin respects the standard ProperDocs 'docs_dir' setting for locating nav files.

```yaml
docs_dir: docs
```

--------------------------------

### Wildcard and DirectoryWildcard Classes

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

This Python code demonstrates the usage of the Wildcard and DirectoryWildcard classes for representing file and directory patterns, respectively. It shows how to access the pattern value.

```python
# File wildcard
w = Wildcard("api", "*.md")
print(w.value)  # "api/*.md"

# Directory wildcard
dw = DirectoryWildcard("docs", "*/")
print(dw.value)  # "docs/*"
```

--------------------------------

### Globbing Files and Directories with glob

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/globber.md

Demonstrates the `glob` method for finding files and directories that match fnmatch-style wildcard patterns. It supports various patterns, including those with multiple wildcards and subdirectory traversal.

```python
globber = MkDocsGlobber(files)

# Match all markdown files in api directory
for path in globber.glob("api/*.md"):
    print(path)
# Output: api/client.md, api/server.md, ...

# Match all directories at top level
for path in globber.glob("*"):
    if globber.isdir(path):
        print(f"Directory: {path}")

# Match with multiple wildcards
for path in globber.glob("docs/*/tutorial/*.md"):
    print(path)
# Output: docs/v1/tutorial/intro.md, docs/v2/tutorial/intro.md, ...

```

--------------------------------

### Hybrid Nav: ProperDocs YAML with Literate Nav Subdirectory

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

Use this configuration in properdocs.yml to keep ProperDocs native nav at the root while deferring a subdirectory to literate-nav. Ensure no nav file exists at the docs root.

```yaml
nav:
  - Frob: index.md
  - Baz: baz.md
  - Borgs: borgs/
```

--------------------------------

### Correct Markdown for Wildcard Item

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/errors.md

Demonstrates the correct Markdown syntax for a wildcard item.

```markdown
* path/to/*.md
```

--------------------------------

### Define Navigation Structure

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/INDEX.md

Create a SUMMARY.md file in your docs directory to define the navigation structure using Markdown lists.

```markdown
* [Home](index.md)
* [Docs](docs/)
```

--------------------------------

### Hybrid Nav Configuration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/INDEX.md

Combine MkDocs' built-in `nav` configuration with the literate-nav plugin, using a wildcard to include remaining pages.

```yaml
# properdocs.yml
nav:
  - Home: index.md
  - Guides: guides/      # Defers to docs/guides/SUMMARY.md
  - '*'                   # Wildcard for remaining pages

plugins:
  - literate-nav
```

--------------------------------

### Standard Plugin Configuration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/INDEX.md

Standard configuration for the literate-nav plugin in mkdocs.yml, including options for nav_file, implicit_index, and tab_length.

```yaml
# properdocs.yml
plugins:
  - literate-nav:
      nav_file: SUMMARY.md
      implicit_index: false
      tab_length: 4
```

--------------------------------

### Importing Literate Nav Components

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

Shows the necessary import statements for using the LiterateNavPlugin, its configuration, and related utility functions in Python.

```python
# Plugin and main functions
from mkdocs_literate_nav.plugin import (
    LiterateNavPlugin,
    PluginConfig,
    resolve_directories_in_nav,
    MkDocsGlobber
)

# Parser
from mkdocs_literate_nav.parser import (
    NavParser,
    Wildcard,
    DirectoryWildcard,
    LiterateNavParseError
)

# Exceptions
from mkdocs_literate_nav.exceptions import LiterateNavError
```

--------------------------------

### Wildcards with Explicit Ordering

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/INDEX.md

Use wildcards in SUMMARY.md to include all files in a directory, combined with explicit ordering for specific files.

```markdown
# docs/SUMMARY.md
* [Introduction](index.md)
* Getting Started
    * [Quickstart](getting-started/quickstart.md)
    * getting-started/*.md
* [API](api/)
```

--------------------------------

### LiterateNavPlugin API

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/MANIFEST.md

Documentation for the LiterateNavPlugin class, including its constructor, lifecycle methods (on_files, on_nav), and related configuration and utility functions.

```APIDOC
## Class LiterateNavPlugin

### Description
The main plugin class for mkdocs-literate-nav. Handles the plugin lifecycle and navigation resolution.

### Constructor
- Initializes the plugin.

### Methods
- **on_files(self, files)**: Processes files during the MkDocs build.
- **on_nav(self, nav, config, files)**: Generates the navigation structure.

### Related Functions
- **resolve_directories_in_nav()**: Resolves directory entries within the navigation structure.
  - Parameters: (nav, config, files)
  - Return Type: Nav
  - Behavior: Traverses the navigation and resolves directory wildcards.
  - Examples: Provided in the source documentation.

### Location
api-reference/plugin.md
```

--------------------------------

### Checking File Globbing with MkDocsGlobber

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

Demonstrates how to use the MkDocsGlobber class to test file globbing patterns against the project's files.

```python
from mkdocs_literate_nav.plugin import MkDocsGlobber

globber = MkDocsGlobber(files)
for f in globber.glob("api/*.md"):
    print(f)
```

--------------------------------

### Module Organization

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/INDEX.md

Shows the directory structure of the mkdocs-literate-nav Python package.

```bash
mkdocs_literate_nav/
├── __init__.py           # Version only
├── plugin.py             # Main plugin, entry point, core functions
├── parser.py             # Navigation parsing logic
└── exceptions.py         # Custom exception definitions
```

--------------------------------

### Initialize Wildcard

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/parser.md

Create a `Wildcard` object to represent a glob pattern in navigation. The `fallback` parameter can store text if the pattern matches nothing.

```python
class Wildcard:
    trim_slash = False

    def __init__(self, *path_parts: str, fallback: bool = True):

```

--------------------------------

### Modern Style Configuration with 2-Space Indentation

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/configuration.md

Enables 2-space indentation for lists and automatically includes index files by configuring nav_file, implicit_index, and tab_length.

```yaml
plugins:
  - literate-nav:
      nav_file: SUMMARY.md
      implicit_index: true
      tab_length: 2

markdown_extensions:
  - mdx_truly_sane_lists
```

--------------------------------

### mkdocs-literate-nav Navigation File Syntax: All files in directory

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

This markdown snippet demonstrates how to include all markdown files within a specific directory using a wildcard pattern.

```markdown
* api/*.md
```

--------------------------------

### Accessing Plugin Configuration Attributes

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

Demonstrates how to access various configuration attributes of the LiterateNavPlugin in Python code.

```python
plugin.config.nav_file
plugin.config.implicit_index
plugin.config.tab_length
plugin.config.markdown_extensions
```

--------------------------------

### Checking Directory Existence with isdir

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/globber.md

Shows how to use the `isdir` method to verify if a given path corresponds to a directory within the indexed files. This method provides O(1) lookup performance.

```python
globber = MkDocsGlobber(files)

if globber.isdir("api"):
    print("api directory exists")

if globber.isdir("api/v1"):
    print("api/v1 subdirectory exists")

if not globber.isdir("missing"):
    print("missing directory does not exist")

```

--------------------------------

### Glob Files and Directories

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/plugin.md

Employ the glob method to find files and directories matching fnmatch-style patterns. This is powerful for dynamic content inclusion or analysis based on file naming conventions.

```python
globber = MkDocsGlobber(files)
# Find all markdown files in usage directory
for path in globber.glob("usage/*.md"):
    print(path)  # usage/foo.md, usage/bar.md, etc.

# Find all directories at any level
for path in globber.glob("*/"):
    print(path)
```

--------------------------------

### mkdocs-literate-nav Navigation File Syntax: All subdirectories

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

This markdown snippet shows how to include all subdirectories within the current level using a wildcard pattern.

```markdown
* */
```

--------------------------------

### MkDocsGlobber Constructor

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/plugin.md

Initializes the MkDocsGlobber with a MkDocs Files collection, building internal indices for efficient lookups.

```APIDOC
## MkDocsGlobber Constructor

### Description
Initializes the globber from a MkDocs Files collection, building internal indices for fast lookups.

### Parameters
#### Path Parameters
- **files** (Files) - Required - MkDocs Files collection to index
```

--------------------------------

### Minimal MkDocs Literate Nav Configuration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/configuration.md

This is the most basic configuration for the literate-nav plugin, using all default settings.

```yaml
plugins:
  - literate-nav
```

--------------------------------

### Inferred File List from Wildcards

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

This list shows the files that would be included in the navigation based on the wildcard patterns in the literate nav file, assuming the files exist.

```text
* index.md
* changelog.md
* credits.md
* usage / bar.md
* usage / baz.md
* usage / foo.md
* tips / stuff.md
* tips / other-stuff.md
* api / Foo.md
* api / Bar / index.md
* api / Bar / Baz.md
```

--------------------------------

### Plugin Ordering for mkdocs-literate-nav

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

This YAML configuration shows the recommended order for the literate-nav plugin within the mkdocs.yml file. It should be placed after plugins that generate or modify files, ensuring it processes the final file set.

```yaml
plugins:
  - search
  - gen-files              # Generates files
  - literate-nav           # Run last (after file modifications)
```

--------------------------------

### Configure Literate Nav Plugin

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/INDEX.md

Configure the literate-nav plugin in your mkdocs.yml file, specifying the navigation file and whether to use implicit indexing.

```yaml
plugins:
  - literate-nav:
      nav_file: SUMMARY.md
      implicit_index: false
```

--------------------------------

### Directory Cross-Links in Nav

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/INDEX.md

Link to entire directories in SUMMARY.md, allowing the plugin to automatically discover and include their contents.

```markdown
# docs/SUMMARY.md
* [Home](index.md)
* [Guides](guides/)
* [API](api/)
```

--------------------------------

### Migrating from GitBook: Theme and Markdown Extensions

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

Theme and markdown_extensions configuration for properdocs.yml when migrating from GitBook, focusing on Material theme and PyMdown extensions.

```yaml
theme:
  name: material
markdown_extensions:
  - pymdownx.highlight
  - pymdownx.magiclink
  - pymdownx.superfences
```

--------------------------------

### Migrating from GitBook: ProperDocs Configuration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

Configuration for properdocs.yml when migrating from GitBook, specifically addressing directory URL handling.

```yaml
use_directory_urls: false
```

--------------------------------

### Wildcard and DirectoryWildcard Types

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/MANIFEST.md

Documentation for the Wildcard and DirectoryWildcard classes, used for pattern matching in navigation.

```APIDOC
## Class Wildcard

### Description
Represents a wildcard pattern for matching file paths.

### Constructor
- Initializes the wildcard with a pattern string.

### Attributes
- Various attributes detailing the pattern's behavior.

### Behavior
- Defines how the pattern matches against file paths.

## Class DirectoryWildcard

### Description
Represents a wildcard pattern specifically for directory matching.

### Inheritance
- Inherits from the **Wildcard** class.

### Location
api-reference/parser.md
```

--------------------------------

### Literate Nav Plugin Configuration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/docs/reference.md

Shows a basic configuration for the literate-nav plugin within `properdocs.yml`, specifying the navigation file and disabling implicit index.

```yaml
plugins:
  - literate-nav:
      nav_file: SUMMARY.md
      implicit_index: false
      tab_length: 4

```

--------------------------------

### MkDocsGlobber Constructor

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/globber.md

Initializes the MkDocsGlobber by building internal indices for files and directories from a MkDocs Files collection.

```APIDOC
## MkDocsGlobber Constructor

### Description
Initializes the globber by scanning the Files collection and building three internal indices: `files`, `dirs`, and `index_dirs`.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from mkdocs.structure.files import Files
from mkdocs_literate_nav.plugin import MkDocsGlobber

# Assuming 'files' is an instance of mkdocs.structure.files.Files
globber = MkDocsGlobber(files)
```

### Response
None

**Behavior**: Indexes only documentation pages, converts paths to PurePosixPath, and handles nested directories.
```

--------------------------------

### Custom Navigation File

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/START_HERE.md

Specify a custom file name for navigation definitions instead of the default SUMMARY.md.

```yaml
plugins:
  - literate-nav:
      nav_file: TABLE_OF_CONTENTS.md
```

--------------------------------

### Correct Markdown for Sublist

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/errors.md

Demonstrates the correct Markdown syntax for a section title with a sublist.

```markdown
* Section Title
    * [Page](page.md)
```

--------------------------------

### mkdocs-literate-nav Navigation File Syntax: Specific order + wildcard rest

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

This markdown snippet defines a specific order for navigation items and then uses a wildcard to include all remaining markdown files.

```markdown
* [Welcome](index.md)
* [Quickstart](quickstart.md)
* *.md              # Everything else
```

--------------------------------

### Markdown Extensions Configuration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/docs/reference.md

Demonstrates how to configure the `literate-nav` plugin to use custom Markdown extensions, such as `mdx_truly_sane_lists`, and also configures it globally for ProperDocs.

```yaml
plugins:
  - literate-nav:
      markdown_extensions:
        - mdx_truly_sane_lists

markdown_extensions:
  - mdx_truly_sane_lists

```

--------------------------------

### NavParser.markdown_to_nav

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/parser.md

Parses a Markdown navigation file from the current directory and converts it into a ProperDocs-compatible navigation structure. It handles implicit index files, wildcard expansion, and falls back to inferring the navigation if no explicit nav file is found.

```APIDOC
## NavParser.markdown_to_nav

### Description
Parses a Markdown navigation file and converts it to a ProperDocs nav structure. It handles implicit index files, wildcard expansion, and falls back to inferring the navigation if no explicit nav file is found.

### Method
`markdown_to_nav`

### Parameters
#### Path Parameters
- **roots** (tuple[str, ...]) - Required - Stack of directory paths, with current directory as first element; used for recursion tracking

### Returns
Navigation structure (list of dicts/strings representing the nav tree).

### Code Example
```python
parser = NavParser(get_nav_for_dir, globber, implicit_index=False)
nav = parser.markdown_to_nav()  # Parse root nav
```
```

--------------------------------

### Correct Markdown for Bare Item

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/errors.md

Shows the correct Markdown for a bare item, including a title and link.

```markdown
* [My Page](path/to/file.md)
```

--------------------------------

### Configure Markdown Extensions

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/configuration.md

Specify markdown extensions to be used when parsing navigation files. Extensions can be simple strings or dictionaries for configuration.

```yaml
plugins:
  - literate-nav:
      markdown_extensions:
        - extra
        - toc
```

```yaml
plugins:
  - literate-nav:
      markdown_extensions:
        - extra
        - toc:
            permalink: true
            title: Table of Contents
```

```yaml
plugins:
  - literate-nav:
      markdown_extensions:
        - mdx_truly_sane_lists
```

--------------------------------

### Check Directory Existence

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/globber.md

Verify if a specific directory exists within the project structure. Useful for conditional logic or fallbacks when a directory is not found.

```python
globber = MkDocsGlobber(files)

if globber.isdir("api/v1"):
    print("API v1 subdirectory found")
else:
    print("API v1 not found, falling back to inferred nav")
```

--------------------------------

### Enabling Debug Logging for Literate Nav

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

Configures Python's logging module to display debug messages from the mkdocs-literate-nav package.

```python
import logging
logging.getLogger("mkdocs.plugins.mkdocs_literate_nav").setLevel(logging.DEBUG)
```

--------------------------------

### Using Markdown Extensions for Indentation

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/configuration.md

This configuration shows how to integrate a Markdown extension like mdx_truly_sane_lists to handle indentation for the entire site, not just navigation files.

```yaml
plugins:
  - literate-nav:
      markdown_extensions:
        - mdx_truly_sane_lists

markdown_extensions:
  - mdx_truly_sane_lists
```

--------------------------------

### YAML Equivalent Navigation

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

The traditional YAML representation of the Markdown navigation structure shown previously.

```yaml
nav:
  - Frob: index.md
  - Baz: baz.md
  - Borgs:
    - index.md
    - Bar: borgs/bar.md
    - Foo: borgs/foo.md
```

--------------------------------

### on_nav Event Handler

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/plugin.md

Validates the nav structure against the current files collection to detect modifications by other plugins. Logs a warning if discrepancies are found.

```python
def on_nav(self, nav: Navigation, config: MkDocsConfig, files: Files) -> None:
    pass
```

--------------------------------

### Hybrid Nav: ProperDocs YAML with Wildcard Subdirectory

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

Use a wildcard in properdocs.yml to inline all files from a subdirectory directly into the current navigation level. This is an alternative to specifying a directory with a slash.

```yaml
nav:
  - Frob: index.md
  - Baz: baz.md
  - borgs/*
```

--------------------------------

### Python Imports for mkdocs-literate-nav

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/START_HERE.md

Provides common import paths for using mkdocs-literate-nav components in Python code, including the main plugin, parser utilities, and exception classes.

```python
# Main plugin
from mkdocs_literate_nav.plugin import LiterateNavPlugin, PluginConfig

# Parser
from mkdocs_literate_nav.parser import NavParser, Wildcard, DirectoryWildcard

# Exceptions
from mkdocs_literate_nav.exceptions import LiterateNavError
from mkdocs_literate_nav.parser import LiterateNavParseError
```

--------------------------------

### glob Method

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/api-reference/globber.md

Finds all files and directories matching a specified glob pattern.

```APIDOC
## glob

### Description
Finds all files and directories matching a glob pattern using fnmatch-style wildcards.

### Method
glob

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
#### Path Parameters
* **pattern** (str) - Required - Glob pattern with `*` wildcard (e.g., "*.md", "api/*.py", "*/index.md")

### Request Example
```python
globber = MkDocsGlobber(files)

# Match all markdown files in api directory
for path in globber.glob("api/*.md"):
    print(path)
```

### Response
#### Success Response (Iterator[str])
* **Iterator[str]** - An iterator yielding matching paths (strings) relative to the docs root.

**Pattern Syntax**: Supports `*` wildcard, multiple wildcards, and traversal into subdirectories. **Behavior**: Converts pattern to regex, matches against indexed paths, and yields results in order.
```

--------------------------------

### Equivalent Subdirectory Inclusion

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/docs/reference.md

An alternative way to include a subdirectory's navigation, equivalent to a subdirectory cross-link. This method uses a subsection title and a wildcard to include all items from the subdirectory.

```markdown
* Foo
  * foo/*
```

--------------------------------

### mkdocs-literate-nav Navigation File Syntax: Nested wildcards

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/QUICK_REFERENCE.md

This markdown snippet illustrates how to use nested wildcard patterns to include files from specific subdirectories within a larger directory structure.

```markdown
* api/
    * api/v1/*.md
    * api/v2/*.md
```

--------------------------------

### 2-Space Indentation Configuration

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/START_HERE.md

Configure the literate-nav plugin to use 2-space indentation for navigation files and enable mdx_truly_sane_lists.

```yaml
plugins:
  - literate-nav:
      tab_length: 2

markdown_extensions:
  - mdx_truly_sane_lists
```

--------------------------------

### MkDocsGlobber API

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/MANIFEST.md

In-depth documentation for MkDocsGlobber, detailing its methods for file system globbing and index finding within the MkDocs context.

```APIDOC
## Class MkDocsGlobber

### Description
Provides utilities for globbing files and finding index files within an MkDocs project.

### Constructor
- Initializes the globber with project context.

### Methods
- **glob(pattern)**
  - Parameters: Glob pattern string.
  - Behavior: Returns a list of files matching the pattern.
  - Examples: Provided in the source documentation.
- **isdir(path)**
  - Parameters: File path.
  - Behavior: Checks if a path is a directory.
  - Performance: Documented for efficiency.
- **find_index(path)**
  - Parameters: Path to search within.
  - Behavior: Locates an index file (e.g., README.md, index.md).
  - Usage: Documented for common use cases.

### Location
api-reference/globber.md
```

--------------------------------

### Correct Markdown for Content After Link

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/_autodocs/errors.md

Shows the correct Markdown syntax where no extra text follows a link.

```markdown
* [Title](page.md)
```

--------------------------------

### Markdown Navigation with Cross-linking

Source: https://github.com/oprypin/mkdocs-literate-nav/blob/master/README.md

Demonstrates cross-linking between parent and child navigation files. The trailing slash in '[Borgs](borgs/)' indicates a separate nav file for that directory.

```markdown
* [Frob](index.md)
* [Baz](baz.md)
* [Borgs](borgs/)
```