docs: Update README to include information about the plugin system

This commit is contained in:
sigmasternchen 2025-01-07 20:38:14 +01:00
parent 7ad0d3eb40
commit 49ad983da0

View file

@ -11,6 +11,7 @@ for programming knowledge — simply modify YAML files to generate your site.
- **Markdown Support**: Write content in Markdown, which is automatically converted to HTML. - **Markdown Support**: Write content in Markdown, which is automatically converted to HTML.
- **Tagging System**: Organize your content with tags for easy referencing in templates. - **Tagging System**: Organize your content with tags for easy referencing in templates.
- **File Inclusion**: Include other YAML files to create a modular content structure. - **File Inclusion**: Include other YAML files to create a modular content structure.
- **Plugin System**: Extend the functionality with modules that can be added at runtime.
## Getting Started ## Getting Started
@ -26,7 +27,7 @@ To generate your static site, run the Grimoire command with your input YAML file
You can specify an output directory using the `-o` or `--output` flag. You can specify an output directory using the `-o` or `--output` flag.
```bash ```bash
python -m grimoire-ssg -o output_directory one_or_more_input_files.yml python -m grimoiressg -o output_directory one_or_more_input_files.yml
``` ```
### Alternative Installation ### Alternative Installation
@ -43,7 +44,7 @@ poetry install
You can then run the program directly using Poetry: You can then run the program directly using Poetry:
```bash ```bash
poetry run python -m grimoire-ssg -o output_directory one_or_more_input_files.yml poetry run python -m grimoiressg -o output_directory one_or_more_input_files.yml
``` ```
### Example YAML File ### Example YAML File
@ -101,7 +102,11 @@ extends a layout and includes dynamic content:
<h2>My latest blog articles:</h2> <h2>My latest blog articles:</h2>
<ul> <ul>
{% for entry in tags["blog"] %} {% for entry in tags["blog"] %}
<li><a href="{{ entry.output }}">{{ entry.title }}</a> ({{ entry.date }})</li> <li>
<a href="{{ entry.output }}">
{{ entry.title }}
</a> ({{ entry.date }})
</li>
{% endfor %} {% endfor %}
</ul> </ul>
{% endblock %} {% endblock %}
@ -126,7 +131,42 @@ Additionally, the following fields are defined:
### Output Structure ### Output Structure
The output files will be generated in the specified output directory, with paths defined in the `output` attribute of your YAML files. The output files will be generated in the specified output directory, with paths defined in the `output`
attribute of your YAML files.
## Advanced Features
### Custom Plugins
The program supports the addition of custom plugins at runtime. To utilize this, create a Python module
that modifies the list of available modules:
```Python
from grimoiressg.modules import available_modules
def test(data, context):
print("This is test module.")
available_modules["test"] = test
```
You then need a config file that loads, and enables this module. Please note that you need to specify
all `enabled_modules` to be used - not just the additional one.
```yaml
load_modules:
- external_module_test
enabled_modules:
- tags # built-in module for tagging
- markdown # built-in module for markdown support
- templating # built-in module for templating
- test # our custom module; the name is the
# key in the `available_modules` dict above
```
## Contributing ## Contributing