Metadata-Version: 2.4
Name: mkdocs-lex-plugin
Version: 0.2.0
Summary: MkDocs plugin that renders .lex files natively, with no precompilation step.
Author-email: Arthur Debert <debert@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Arthur Debert
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/lex-fmt/mkdocs-lex
Project-URL: Repository, https://github.com/lex-fmt/mkdocs-lex
Project-URL: Issues, https://github.com/lex-fmt/mkdocs-lex/issues
Project-URL: Lex Language, https://github.com/lex-fmt/lex
Keywords: mkdocs,mkdocs-plugin,lex,documentation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs>=1.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# mkdocs-lex

A native Lex parser and integration for MkDocs.

This plugin allows MkDocs to seamlessly parse and render `.lex` files as part of your documentation site. It acts as a transparent adapter—MkDocs treats your `.lex` files as native Markdown pages, meaning all of your favorite MkDocs features, themes, and plugins will continue to work perfectly!

> [!NOTE]
> This plugin needs the `lexd` CLI to convert your `.lex` files. By default it will download the right binary for your platform from the latest `lex-fmt/lex` release on first run and cache it under `.mkdocs_lex_cache/` — no manual install needed. If you already have `lexd` on your `PATH`, it'll use that instead.

## Installation

Install the package via pip:

```bash
pip install mkdocs-lex-plugin
```

## Usage

To enable the plugin, add `lex` to the `plugins` section of your `mkdocs.yml`:

```yaml
site_name: My Documentation

plugins:
  - search
  - lex
```

### Configuration Options

| Option | Default | Description |
|--------|---------|-------------|
| `download_if_missing` | `true` | When `lexd` isn't on `PATH`, fetch the latest matching binary from the `lex-fmt/lex` GitHub releases and cache it under `.mkdocs_lex_cache/`. Set to `false` to require a pre-installed `lexd` and error out if it's missing. |

```yaml
plugins:
  - search
  - lex:
      download_if_missing: false   # require pre-installed lexd
```

### Navigation Configuration

Because the plugin tricks MkDocs into treating your `.lex` files as Markdown, your `mkdocs.yml` navigation must point to `.md` extensions, even though the files on disk are `.lex`. 

For example, if you have `docs/getting-started.lex` and `docs/index.lex`:

```yaml
nav:
  - Home: index.md
  - Getting Started: getting-started.md
```

## Development Setup

If you want to contribute or test this plugin locally:

1. Clone the repository: `git clone https://github.com/lex-fmt/mkdocs-lex`
2. Run the development setup script: `bash scripts/setup-dev-env.sh`
3. Activate the virtual environment: `source .venv/bin/activate`
4. Run integration tests: `pytest tests/`

## How it works

MkDocs is fundamentally a Markdown engine. This plugin integrates cleanly by:
1. Identifying `.lex` files in your `docs/` folder.
2. Tricking MkDocs' internal engine into believing they are `.md` pages.
3. Intercepting the file-read hook (`on_page_read_source`) to perform a just-in-time conversion of Lex to Markdown using the `lexd convert` capability.

This means no temporary `.md` files clutter your repo, and live-reloading (`mkdocs serve`) works natively when you edit a `.lex` file!
