Metadata-Version: 2.4
Name: mkdocs-note
Version: 1.0.1
Summary: A MkDocs plugin to add note boxes to your documentation.
Home-page: https://github.com/virtualguard101/mkdocs-note
Author: virtualguard101
Author-email: virtualguard101 <virtualguard101@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/virtualguard101/mkdocs-note
Project-URL: Issues, https://github.com/virtualguard101/mkdocs-note/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs>=1.6.1
Requires-Dist: colorlog>=6.9.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest-cov; extra == "test"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# MkDocs-Note

<!-- [![PyPI version](https://badge.fury.io/py/mkdocs-note.svg)](https://badge.fury.io/py/mkdocs-note) -->

`MkDocs-Note` is a plugin for `MkDocs` that automatically manages notes in your documentation site. It's designed to work seamlessly with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme to create a unified note-taking and documentation experience.

## Features

- **Recent Notes Display**: Automatically displays a list of recent notes on your notes index page

- **Multi-format Support**: Supports both Markdown (.md) and Jupyter Notebook (.ipynb) files

- **Smart Filtering**: Excludes index files and other specified patterns from the recent notes list

- **Flexible Configuration**: Highly customizable note directory, file patterns, and display options

- **Automatic Updates**: Notes list updates automatically when you build your documentation

## Installation

Recommanded to use [uv](https://docs.astral.sh/uv/) to manage python virtual environment:

```
uv venv
uv pip insatll mkdocs-note
```

Or using `pip`:

```bash
pip install mkdocs-note
```

Then, add the plugin to your `mkdocs.yml`:

```yaml
plugins:
  - mkdocs-note:
      enabled: true
      notes_dir: "docs/notes"
      index_file: "docs/notes/index.md"
      max_notes: 10
      start_marker: "<!-- recent_notes_start -->"
      end_marker: "<!-- recent_notes_end -->"
```

> **⚠️ Important**: Note the indentation! Use **spaces** (not dashes `-`) for plugin options. The configuration must be a dictionary, not a list. See [Troubleshooting Guide](TROUBLESHOOTING.md) for common configuration issues.

## Usage

### Setting Up Your Notes Directory

1. Create a notes directory in your documentation (e.g., `docs/notes/`)
2. Create an `index.md` file in your notes directory
3. Add the marker comments to your index file:

```markdown
# My Notes

<!-- recent_notes_start -->
<!-- recent_notes_end -->
```

### Configuration Options

The plugin supports the following configuration options in your `mkdocs.yml`:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | bool | `true` | Enable or disable the plugin |
| `notes_dir` | Path | `"docs/notes"` | Directory containing your notes |
| `index_file` | Path | `"docs/notes/index.md"` | Index file where recent notes will be displayed |
| `max_notes` | int | `10` | Maximum number of recent notes to display |
| `start_marker` | str | `"<!-- recent_notes_start -->"` | Start marker for notes insertion |
| `end_marker` | str | `"<!-- recent_notes_end -->"` | End marker for notes insertion |
| `supported_extensions` | Set[str] | `{".md", ".ipynb"}` | File extensions to include as notes |
| `exclude_patterns` | Set[str] | `{"index.md", "README.md"}` | File patterns to exclude |
| `exclude_dirs` | Set[str] | `{"__pycache__", ".git", "node_modules"}` | Directories to exclude |

### How It Works

1. The plugin scans your configured notes directory for supported file types
2. It extracts metadata (title, modification date) from each note file
3. Notes are sorted by modification time (most recent first)
4. The specified number of recent notes is inserted into your index page between the marker comments
5. The process runs automatically every time you build your documentation

## Contributing

Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines.

## License

This project is licensed under the [GNU General Public License v3.0](LICENSE).
