nginx_alias_map: A Plugin for Pelican
====================================================
[](https://github.com/gaige/nginx_alias_map/actions)
[](https://pypi.org/project/pelican-nginx-alias-map/)
This Pelican plugin creates an nginx-compatible map between the final page locations
and prior locations, defined in the "Alias" attribute for any article or page.
Loosely based on [pelican-alias](https://github.com/Nitron/pelican-alias) by Chris Williams,
which itself was inspired by jekyll_alias_generator.
Installation
------------
This plugin can be installed via:
python -m pip install pelican-nginx-alias-map
Usage
-----
Add the directory to the base plugins directory to `PLUGIN_PATHS` in
`pelicanconf.py`, and then add `nginx_alias_map` to the `PLUGINS` list. For example,
PLUGIN_PATHS = ["plugins"]
PLUGINS = ['nginx_alias_map']
Definable parameters (with defaults in brackets) allow some configuration of the output
of the plugin.
There are two definable parameters, one from Chris's code (`ALIAS_DELIMITER`), which
defines the delimiter for multiple aliases for the same item; and `ALIAS_FILE`, which
defines the final name of the output file containing the map; and
ALIAS_DELIMITER : Delimeter between multiple aliases for the same item [","]
ALIAS_FILE : Name of map file to be placed in `output` ['alias_map.txt']
ALIAS_MAP : Name of the map used in the alias file ['redirect_uri']
ALIAS_MAP_TEMP: Name of the map used in the alias file when 2-stage lookup is needed ['redirect_uri_1']
### Support for URLs with query strings
In the event that you need to redirect a URI that contains a query string, a separate
map block will be created to map the `$request_uri` against an re.escaped version of your
alias that contains the `?` character. Otherwise, when no query string is present, the
test is made against `$uri`, which has much more processing done with it (query string
removal, removal of unnecessary '/'s, and so forth).
### NGINX configuration
The resulting file (stored in `output/$(ALIAS_FILE)`) is ready to be included into
your nginx configuration file (in an http stanza). Once the map is created, use the
`ALIAS_MAP` variable in your processing.
include /opt/web/output/alias_map.txt;
server {
listen *:80 ssl;
server_name example.server;
# Redirection logic
if ( $redirect_uri ) {
return 301 $redirect_uri;
}
location / {
alias /opt/web/output;
}
}
This configuration uses the evil `if` statement, but it's concise. If you have a better
approach, please create a pull request, and I'll add it to this doc (or replace it if it
makes more sense).
I've chosen to use a 301 redirect here, because I'm confident of the permanency. During
testing, you may want to use a 302.
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/gaige/nginx_alias_map/issues
[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html
Updating
--------
We use dependabot for updating dependencies, conventional commits for commit messages,
and github actions for release.
To generate a release:
1. `cz bump --dry-run [--increment patch]` to verify changes
2. `cz bump [--increment patch]` to finalize
3. `git push` to send code and `git push <tag>` to send the tag (or the less-safe `--tags`)
License
-------
This project is licensed under the MIT license.
Raw data
{
"_id": null,
"home_page": "https://github.com/gaige/nginx_alias_map",
"name": "pelican-nginx-alias-map",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "pelican, plugin",
"author": "Gaige B. Paulsen",
"author_email": "gaige@cluetrust.com",
"download_url": "https://files.pythonhosted.org/packages/4e/89/36d35fa4bca3209ef0334d1ad10a31ac907e170e9666b87f530d2f2e6ac5/pelican_nginx_alias_map-2.0.5.tar.gz",
"platform": null,
"description": "nginx_alias_map: A Plugin for Pelican\n====================================================\n\n[](https://github.com/gaige/nginx_alias_map/actions)\n[](https://pypi.org/project/pelican-nginx-alias-map/)\n\n\n\nThis Pelican plugin creates an nginx-compatible map between the final page locations\nand prior locations, defined in the \"Alias\" attribute for any article or page.\n\nLoosely based on [pelican-alias](https://github.com/Nitron/pelican-alias) by Chris Williams,\nwhich itself was inspired by jekyll_alias_generator.\n\nInstallation\n------------\n\nThis plugin can be installed via:\n\n python -m pip install pelican-nginx-alias-map\n\nUsage\n-----\n\nAdd the directory to the base plugins directory to `PLUGIN_PATHS` in\n`pelicanconf.py`, and then add `nginx_alias_map` to the `PLUGINS` list. For example,\n\n PLUGIN_PATHS = [\"plugins\"]\n PLUGINS = ['nginx_alias_map']\n\nDefinable parameters (with defaults in brackets) allow some configuration of the output\nof the plugin.\n\nThere are two definable parameters, one from Chris's code (`ALIAS_DELIMITER`), which\ndefines the delimiter for multiple aliases for the same item; and `ALIAS_FILE`, which\ndefines the final name of the output file containing the map; and\n\n ALIAS_DELIMITER : Delimeter between multiple aliases for the same item [\",\"]\n ALIAS_FILE : Name of map file to be placed in `output` ['alias_map.txt']\n ALIAS_MAP : Name of the map used in the alias file ['redirect_uri']\n ALIAS_MAP_TEMP: Name of the map used in the alias file when 2-stage lookup is needed ['redirect_uri_1']\n\n### Support for URLs with query strings\n\nIn the event that you need to redirect a URI that contains a query string, a separate\nmap block will be created to map the `$request_uri` against an re.escaped version of your\nalias that contains the `?` character. Otherwise, when no query string is present, the\ntest is made against `$uri`, which has much more processing done with it (query string\nremoval, removal of unnecessary '/'s, and so forth).\n\n### NGINX configuration\n\nThe resulting file (stored in `output/$(ALIAS_FILE)`) is ready to be included into\nyour nginx configuration file (in an http stanza). Once the map is created, use the\n`ALIAS_MAP` variable in your processing.\n\n include /opt/web/output/alias_map.txt;\n\n server {\n listen *:80 ssl;\n server_name example.server;\n\n\n # Redirection logic\n if ( $redirect_uri ) {\n return 301 $redirect_uri;\n }\n\n location / {\n alias /opt/web/output;\n }\n }\n\nThis configuration uses the evil `if` statement, but it's concise. If you have a better\napproach, please create a pull request, and I'll add it to this doc (or replace it if it\nmakes more sense).\n\nI've chosen to use a 301 redirect here, because I'm confident of the permanency. During\ntesting, you may want to use a 302.\n\nContributing\n------------\n\nContributions 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][].\n\nTo start contributing to this plugin, review the [Contributing to Pelican][] documentation, beginning with the **Contributing Code** section.\n\n[existing issues]: https://github.com/gaige/nginx_alias_map/issues\n[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html\n\nUpdating\n--------\n\nWe use dependabot for updating dependencies, conventional commits for commit messages,\nand github actions for release.\n\nTo generate a release:\n\n1. `cz bump --dry-run [--increment patch]` to verify changes\n2. `cz bump [--increment patch]` to finalize\n3. `git push` to send code and `git push <tag>` to send the tag (or the less-safe `--tags`)\n\n\nLicense\n-------\n\nThis project is licensed under the MIT license.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "This Pelican plugin creates an nginx-compatible map between the final page locations and prior locations, defined in the `Alias` attribute for any article or page.",
"version": "2.0.5",
"project_urls": {
"Documentation": "https://docs.getpelican.com",
"Homepage": "https://github.com/gaige/nginx_alias_map",
"Issue Tracker": "https://github.com/gaige/nginx_alias_map/issues",
"Repository": "https://github.com/gaige/nginx_alias_map"
},
"split_keywords": [
"pelican",
" plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ae1e8586f079525bab898590b037e6f93c1f66e2433de545a2bee3b8d33b933a",
"md5": "80086b5074f08579f2f1aed29a963c44",
"sha256": "53c4b9dbed0398acdaab43a9dbc6687988f2dd95f4078aacfd819674a7988405"
},
"downloads": -1,
"filename": "pelican_nginx_alias_map-2.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "80086b5074f08579f2f1aed29a963c44",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 7555,
"upload_time": "2024-11-28T17:08:57",
"upload_time_iso_8601": "2024-11-28T17:08:57.663256Z",
"url": "https://files.pythonhosted.org/packages/ae/1e/8586f079525bab898590b037e6f93c1f66e2433de545a2bee3b8d33b933a/pelican_nginx_alias_map-2.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4e8936d35fa4bca3209ef0334d1ad10a31ac907e170e9666b87f530d2f2e6ac5",
"md5": "ed60901d4b9199d146ec370b72aab0a9",
"sha256": "c738012efab42acc9239e2bc4d8f44b5d5f68179d28b7c4fe858b7fc10147cd6"
},
"downloads": -1,
"filename": "pelican_nginx_alias_map-2.0.5.tar.gz",
"has_sig": false,
"md5_digest": "ed60901d4b9199d146ec370b72aab0a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 5903,
"upload_time": "2024-11-28T17:08:59",
"upload_time_iso_8601": "2024-11-28T17:08:59.372017Z",
"url": "https://files.pythonhosted.org/packages/4e/89/36d35fa4bca3209ef0334d1ad10a31ac907e170e9666b87f530d2f2e6ac5/pelican_nginx_alias_map-2.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-28 17:08:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gaige",
"github_project": "nginx_alias_map",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pelican-nginx-alias-map"
}
JSON
