diff --git a/README.md b/README.md new file mode 100644 index 0000000..bc4e6d2 --- /dev/null +++ b/README.md @@ -0,0 +1,133 @@ +# Grimoire SSG + +Grimoire is a minimalistic Static Site Generator (SSG) designed to simplify the process of +creating static websites. With Grimoire, most use cases can be addressed without the need +for programming knowledge — simply modify YAML files to generate your site. + +## Features + +- **YAML Configuration**: Define your content and structure using simple YAML files. +- **Template Rendering**: Utilize Jinja2 templates for dynamic content generation. +- **Markdown Support**: Write content in Markdown, which is automatically converted to HTML. +- **Tagging System**: Organize your content with tags for easy referencing in templates. +- **File Inclusion**: Include other YAML files to create a modular content structure. + +## Getting Started + +### Installation + +To get started with Grimoire, clone the repository and install the required dependencies: + +```bash +git clone https://github.com/sigmasternchen/grimoire-ssg.git +cd grimoire-ssg +poetry install +``` + +### Usage + +To generate your static site, run the Grimoire command with your input YAML files. You can specify an output directory using the `-o` or `--output` flag. + +```bash +poetry run python -m grimoire -o output_directory input_file.yml +``` + +### Example YAML File + +Here is an example of a YAML file that defines a content structure: + +```yaml +# (optional) Included files will also be considered for generation. +# If this attribute is missing or empty, no other files will be included. +include: + - pages/*.yml + - blog/*.yml + +# (optional) List of tags for this file. +# These can be used in templates later to reference this content. +# If this attribute is missing or empty, this file will not be accessible +# via any tags. +tags: + - page + +# (optional) The file that should be generated from this .yml file. +# If this attribute is missing, no output file will be generated. +output: index.html + +# (optional) Path to the template for this .yml file. +# If this attribute is missing, no output will be generated. +# It's also possible to just use `template` without `output`. In that case +# the rendered template can still be accessed by other templates. +template: ../templates/homepage.html + +# (optional) The markdown content for this output file. +# If this attribute is missing, the markdown content can not be +# referenced by the template. +markdown: | + # Hello, World! + +# All other defined attributes are not interpreted by the program, but +# can still be referenced by a template. +# The following are some examples: +Date: 2025-01-06 +Author: Sigma +``` + +### Template Example + +Grimoire uses Jinja2 templates for rendering. Below is an example of a template that +extends a layout and includes dynamic content: + +```jinja +{% extends template_dir + "/layout.templ.html" %} +{% block title %}Homepage{% endblock %} +{% block content %} + {{ current.markdown_compiled | safe }} + +