# NGINX Markdown for Agents

<!-- BUILD NOTE: This file is a build-time copy included inside .deb/.rpm
     packages at /usr/share/doc/nginx-markdown-for-agents/README.md.
     The canonical project documentation lives at:
     https://github.com/cnkang/nginx-markdown-for-agents

     Do NOT edit this file as a standalone document. Changes should be made
     to the source in packaging/docs/README.md and rebuilt. (Single-source
     policy — see docs/ in the project repository.) -->

## Overview

**nginx-markdown-for-agents** is an NGINX dynamic filter module that serves
Markdown to AI agents while keeping HTML for normal browser clients.

Clients that send `Accept: text/markdown` receive a Markdown representation
of the page. Browsers and other clients continue to receive the original HTML.
You can also target specific bots by User-Agent so they receive Markdown
automatically.

## Quick Start

After installing this package:

1. Add to `nginx.conf` (top-level, before the `http` block):

   ```nginx
   load_module modules/ngx_http_markdown_filter_module.so;
   ```

2. Verify configuration:

   ```bash
   sudo nginx -t
   ```

3. Reload NGINX:

   ```bash
   sudo systemctl reload nginx
   ```

4. Test the module:

   ```bash
   curl -H "Accept: text/markdown" http://localhost/
   ```

For detailed installation and configuration instructions, see:

- **Full documentation**: <https://github.com/cnkang/nginx-markdown-for-agents>
- **Installation guide**: `INSTALL.md` (included in this package)
- **Compatibility info**: `COMPATIBILITY.md` (included in this package)

## Compatibility Warning

> **IMPORTANT**: This prebuilt package is compiled against a specific
> nginx.org stable release. It is **ONLY** compatible with the exact
> nginx.org version indicated in the package filename.

NGINX dynamic modules are **NOT** universal shared libraries. Each module
is compiled against a specific NGINX source version and validated via a
binary compatibility signature at load time. If the signature does not
match, NGINX will refuse to load the module.

This package does **NOT** support:

- Distribution-provided NGINX packages (Ubuntu/Debian apt, RHEL/CentOS yum)
- Vendor-patched NGINX builds
- OpenResty
- Tengine
- Custom-compiled NGINX binaries

If your NGINX version is not supported by a prebuilt package, please build
the module from source against your local NGINX source tree. See
`COMPATIBILITY.md` for details.

## License

This project is licensed under the **BSD 2-Clause License**.
See the `LICENSE` file installed at
`/usr/share/licenses/nginx-markdown-for-agents/LICENSE` for the full text.

## Links

- **Source code**: <https://github.com/cnkang/nginx-markdown-for-agents>
- **Releases**: <https://github.com/cnkang/nginx-markdown-for-agents/releases>
- **Issues**: <https://github.com/cnkang/nginx-markdown-for-agents/issues>
