pelican-data-files 1.3.0

Pelican plugin that allows to load data from files like JSON or YAML.

---

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 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.

This plugin is avaiable as a python package hosted on PyPI.

Setup

All you have to do is install the latest version of the package with pip:

pip install pelican-data-files

For additional filetypes, you may install variants like this:

# 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).

To be sure, run this command which displays all the registered plugins, pelican-data-files should be printed:

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:

{
  "firstname": "John",
  "lastname": "Doe",
  "age": 25,
  "contact": {
    "phone": "[phone]",
    "mail": "[e-mail]"
  }
}

Then, see what following queries return:

DATA_PROFILE["firstname"] => "John"
DATA_PROFILE["age"] => 25
DATA_PROFILE["contact"]["mail"] => "[e-mail]"

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):

...
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:

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 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.