<!-- markdownlint-disable MD041 -->
---
> Pelican plugin that allows to load data from files like JSON or YAML.
This plugin loads all the data files found in the project's `content/data/` directory, and makes them accessible in jinja templates by injecting them into the context (with the prefix `DATA_` followed by the name of the file).
This is roughly the default behavior of the well known [Jekyll](https://jekyllrb.com/) static site generator.
For example, the data of a `profile.json` file will be accessible from any template via `DATA_PROFILE`.
## Getting started
You can use it directly in a personal project or to build a [Pelican theme](https://docs.getpelican.com/en/stable/themes.html).
This plugin is avaiable as a [python package](https://pypi.org/project/pelican-data-files/) hosted on PyPI.
### Setup
All you have to do is install the latest version of the package with pip:
```bash
pip install pelican-data-files
```
For additional filetypes, you may install variants like this:
```bash
# TOML
pip install pelican-data-files[toml]
# YAML
pip install pelican-data-files[yaml]
# Both
pip install pelican-data-files[toml,yaml]
```
**Note**: When using multiple data handlers, files with the same name will be prioritized by modified date, so between `profile.json` and `profile.yaml`, only the newer / more recently changed one will be picked up!
By default, Pelican will automatically discover and register the plugin (see more [here](https://docs.getpelican.com/en/stable/plugins.html#how-to-use-plugins)).
To be sure, run this command which displays all the registered plugins, `pelican-data-files` should be printed:
```bash
pelican-plugins
```
### Usage
Place some JSON valid files into `data/` folder. Then you can acces your data by querying `DATA_<FILE_NAME>["<VAR_NAME>"]`
For example, consider a simple file named `profile.json` with the followed content:
```json
{
"firstname": "John",
"lastname": "Doe",
"age": 25,
"contact": {
"phone": "+1 302-516-3307",
"mail": "john@doe.com"
}
}
```
Then, see what following queries return:
```python
DATA_PROFILE["firstname"] => "John"
DATA_PROFILE["age"] => 25
DATA_PROFILE["contact"]["mail"] => "john@doe.com"
```
So, you can access all the data in `data/` folder in jinja templates from pelican context.
### Build a theme
It is of course possible to create a theme that uses this plugin, it will not necessarily be dependent on it but must in all cases be designed for. (Usage of `DATA_` prefix in theme templates and provide sample data files)
First set the plugin (or its variants, see above) as an install requirement, for example with a package managed with setuptools (`setup.py`):
```python
...
install_requires=[
"pelican",
"pelican-data-files"
],
...
```
Next, you have to provide sample data files for your theme.
Users can easily fetch the files in their pelican project by running the following command:
```bash
pelican-data-files --fetch <THEME_NAME>
```
This will copy the `data/` folder of the theme into the `content/data/` folder of their Pelican project.
They will only have to modify the files and generate their site.
## Example
[orbelican](https://github.com/LucasVanHaaren/orbelican) is a theme which use pelican-data-files plugin to build an online resume from orbit-theme.
MIT License
Copyright (c) 2020 vhash
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/LucasVanHaaren/pelican-data-files",
"name": "pelican-data-files",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "pelican,pelican-plugin,data",
"author": "vhash",
"author_email": "vanhaaren.lucas+dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7c/b1/aa90eb2881e971bd4b93f0d7b5b2c29b523fb33ece27a03daec470df795d/pelican-data-files-1.3.0.tar.gz",
"platform": null,
"description": "<!-- markdownlint-disable MD041 -->\n\n\n\n\n\n\n\n---\n\n> Pelican plugin that allows to load data from files like JSON or YAML.\n\nThis plugin loads all the data files found in the project's `content/data/` directory, and makes them accessible in jinja templates by injecting them into the context (with the prefix `DATA_` followed by the name of the file).\n\nThis is roughly the default behavior of the well known [Jekyll](https://jekyllrb.com/) static site generator.\n\nFor example, the data of a `profile.json` file will be accessible from any template via `DATA_PROFILE`.\n\n## Getting started\n\nYou can use it directly in a personal project or to build a [Pelican theme](https://docs.getpelican.com/en/stable/themes.html).\n\nThis plugin is avaiable as a [python package](https://pypi.org/project/pelican-data-files/) hosted on PyPI.\n\n### Setup\n\nAll you have to do is install the latest version of the package with pip:\n\n```bash\npip install pelican-data-files\n```\n\nFor additional filetypes, you may install variants like this:\n\n```bash\n# TOML\npip install pelican-data-files[toml]\n\n# YAML\npip install pelican-data-files[yaml]\n\n# Both\npip install pelican-data-files[toml,yaml]\n```\n\n**Note**: When using multiple data handlers, files with the same name will be prioritized by modified date, so between `profile.json` and `profile.yaml`, only the newer / more recently changed one will be picked up!\n\nBy default, Pelican will automatically discover and register the plugin (see more [here](https://docs.getpelican.com/en/stable/plugins.html#how-to-use-plugins)).\n\nTo be sure, run this command which displays all the registered plugins, `pelican-data-files` should be printed:\n\n```bash\npelican-plugins\n```\n\n### Usage\n\nPlace some JSON valid files into `data/` folder. Then you can acces your data by querying `DATA_<FILE_NAME>[\"<VAR_NAME>\"]`\n\nFor example, consider a simple file named `profile.json` with the followed content:\n\n```json\n{\n \"firstname\": \"John\",\n \"lastname\": \"Doe\",\n \"age\": 25,\n \"contact\": {\n \"phone\": \"+1 302-516-3307\",\n \"mail\": \"john@doe.com\"\n }\n}\n```\n\nThen, see what following queries return:\n\n```python\nDATA_PROFILE[\"firstname\"] => \"John\"\nDATA_PROFILE[\"age\"] => 25\nDATA_PROFILE[\"contact\"][\"mail\"] => \"john@doe.com\"\n```\n\nSo, you can access all the data in `data/` folder in jinja templates from pelican context.\n\n### Build a theme\n\nIt is of course possible to create a theme that uses this plugin, it will not necessarily be dependent on it but must in all cases be designed for. (Usage of `DATA_` prefix in theme templates and provide sample data files)\n\nFirst set the plugin (or its variants, see above) as an install requirement, for example with a package managed with setuptools (`setup.py`):\n\n```python\n...\ninstall_requires=[\n \"pelican\",\n \"pelican-data-files\"\n],\n...\n```\n\nNext, you have to provide sample data files for your theme.\n\nUsers can easily fetch the files in their pelican project by running the following command:\n\n```bash\npelican-data-files --fetch <THEME_NAME>\n```\n\nThis will copy the `data/` folder of the theme into the `content/data/` folder of their Pelican project.\n\nThey will only have to modify the files and generate their site.\n\n## Example\n\n[orbelican](https://github.com/LucasVanHaaren/orbelican) is a theme which use pelican-data-files plugin to build an online resume from orbit-theme.\n\nMIT License\n\nCopyright (c) 2020 vhash\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pelican plugin that allows to load data from files like JSON or YAML.",
"version": "1.3.0",
"split_keywords": [
"pelican",
"pelican-plugin",
"data"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b92c65e195d9df229975c5aadc5884f4580b9cb164d14f65b0e925114cd0c4bd",
"md5": "dd288305e38a98c2baceae9477beb209",
"sha256": "2a0a01ea31dcfae7379cb6f4d05b9663671c6aaa02024260ce5514a7f7de71b5"
},
"downloads": -1,
"filename": "pelican_data_files-1.3.0-py3.10.egg",
"has_sig": false,
"md5_digest": "dd288305e38a98c2baceae9477beb209",
"packagetype": "bdist_egg",
"python_version": "1.3.0",
"requires_python": ">=3.6",
"size": 13203,
"upload_time": "2023-04-23T09:25:29",
"upload_time_iso_8601": "2023-04-23T09:25:29.039073Z",
"url": "https://files.pythonhosted.org/packages/b9/2c/65e195d9df229975c5aadc5884f4580b9cb164d14f65b0e925114cd0c4bd/pelican_data_files-1.3.0-py3.10.egg",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7cb1aa90eb2881e971bd4b93f0d7b5b2c29b523fb33ece27a03daec470df795d",
"md5": "850c58ccca8dbb89adcaadf499785227",
"sha256": "ea094def072207419e4a3396c2a14bdf01c385d8589d908b63e7ecfc9e3968a6"
},
"downloads": -1,
"filename": "pelican-data-files-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "850c58ccca8dbb89adcaadf499785227",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7806,
"upload_time": "2023-04-23T09:25:31",
"upload_time_iso_8601": "2023-04-23T09:25:31.595848Z",
"url": "https://files.pythonhosted.org/packages/7c/b1/aa90eb2881e971bd4b93f0d7b5b2c29b523fb33ece27a03daec470df795d/pelican-data-files-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-23 09:25:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "LucasVanHaaren",
"github_project": "pelican-data-files",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pelican-data-files"
}
JSON
