Metadata-Version: 2.1
Name: lm-pelican-engrave
Version: 0.0.1
Summary: A plugin for generating and embedding QR codes in your blogpost
Keywords: pelican,plugin,qrcode,qr,blog,url
Author-Email: Lukas Muenter <lukas.muenter@protonmail.com>
License: MIT
Classifier: Development Status :: 1 - Planning
Classifier: Environment :: Console
Classifier: Framework :: Pelican
Classifier: Framework :: Pelican :: Plugins
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Project-URL: Homepage, https://github.com/lmuenter/pelican-engrave
Project-URL: Issue tracker, https://github.com/lmuenter/pelican-engrave/issues
Project-URL: Funding, https://donate.getpelican.com/
Requires-Python: <4.0,>=3.8.1
Requires-Dist: pelican>=4.5
Requires-Dist: qrcode[pil]>=7.0
Requires-Dist: markdown>=3.4; extra == "markdown"
Provides-Extra: markdown
Description-Content-Type: text/markdown

# Engrave: QR Codes for Pages and Articles

[![Build Status](https://img.shields.io/github/actions/workflow/status/pelican-plugins/engrave/main.yml?branch=main)](https://github.com/lmuenter/pelican-engrave/actions)
[![PyPI Version](https://img.shields.io/pypi/v/pelican-engrave)](https://pypi.org/project/pelican-engrave/)
[![Downloads](https://img.shields.io/pypi/dm/pelican-engrave)](https://pypi.org/project/pelican-engrave/)
![License](https://img.shields.io/pypi/l/pelican-engrave?color=blue)

**Engrave** is a generates QR codes for the URLs of your Pelican posts and pages.

## Installation

This plugin can be installed via:

```bash
python -m pip install pelican-engrave
```

As long as you have not explicitly added a `PLUGINS` setting to your Pelican settings file, then the newly-installed plugin should be automatically detected and enabled. Otherwise, you must add `engrave` to your existing `PLUGINS` list. For more information, please see the [How to Use Plugins](https://docs.getpelican.com/en/latest/plugins.html#how-to-use-plugins) documentation.

## Usage

Engrave automatically generates QR codes for all articles and pages in your Pelican site. These QR codes are saved as SVG images in the `engrave/` directory within the `OUTPUT_PATH` defined in your Pelican settings.

### Accessing QR Codes in Templates

The generated QR code is available in the context of the content as `content.engrave_qrcode`. You can embed the QR code in your templates using the following syntax:

```html
<img src="{{ content.engrave_qrcode }}">
```

### Engrave Directory Cleanup

Before generating new QR codes, Engrave clears the `engrave/` directory to ensure that no legacy QR codes remain. This aims at maintaining security and consistency. Only by latest codes are available this way.

### Schema Validation

Engrave validates URL schemas to ensure security. By default, it only allows URLs with the `https` schema. If your site uses another schema (e.g., `http` or even `ftp`), you should add it to the allowed schemas in your Pelican settings.

### Setting Allowed Schemas

To specify allowed URL schemas for QR code generation, use the `ENGRAVE_ALLOWED_SCHEMES` setting in your Pelican configuration file (`pelicanconf.py`). For example:

```python
ENGRAVE_ALLOWED_SCHEMES = ["https", "http"]
```

### Required Settings

- **SITEURL**: Ensure that `SITEURL` is set in your Pelican configuration file. This setting is crucial as it forms the basis of the URLs used for QR code generation. Be sure to synchronize `ENGRAVE_ALLOWED_SCHEMES` with your `SITEURL` setting to avoid any discrepancies.

## Contributing

Contributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on [existing issues][].

To start contributing to this plugin, review the [Contributing to Pelican][] documentation, beginning with the **Contributing Code** section.

[existing issues]: https://github.com/lmuenter/pelican-engrave/issues
[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html

### Development

To set up a development environment for Engrave, follow these steps.

1. Create and activate the venv:
```
python -m venv venv
source venv/bin/activate
```

2. Install dependencies
```
python -m pip install -r requirements.txt
```

## License

This project is licensed under the MIT license.
