Merge branch 'main' into fix__18_rename_metadata_engine_to_template_e…

…ngine

README.md

@@ -1,16 +1,12 @@
-# JSSG - Jtremesay's Static Site Generator
-
-[![CI/CD](https://github.com/jtremesay/jssg/actions/workflows/main.yaml/badge.svg)](https://github.com/jtremesay/jssg/actions/workflows/main.yaml)
-
-The thing that propulse [jtremesay.org](https://jtremesay.org).
+# JFM-Engine
 
 Today, it's a django app that can generate a static website with Vite & Typescript integration.
 
 ## Bootstrap
 
 ```shell
-$ git clone https://github.com/jtremesay/jtremesay.org.git
-$ cd jtremesay.org
+$ git clone https://github.com/algoo/jssg.git
+$ cd jssg
 $ python3.9 -m venv env/
 $ source env/bin/activate
 $ direnv allow
@@ -44,10 +40,69 @@ $ ./manage.py distill-local --collectstatic --force dist
 Or, if you prefer docker:
 
 ```shell
-$ docker build -t jssg .
-$ sudo docker run -p 8080:80 jssg:latest
+$ sudo docker build -t jssg .
+$ sudo docker network create traefik_public
+$ sudo docker compose up
 ```
 
+## Config
+
+### `settings.py` :
+For django settings, see https://docs.djangoproject.com/en/5.0/ref/settings/
+
+Otherwise, you have to configure the following settings :
+- `JFME_DOMAIN` : the domain name of your website, for instance `"https://www.example.com"` (used in sitemap file)
+- `JFME_CONTENT_DIRS` : a list of directories where to look for the site content
+
+### `Dockerfile` :
+- In the `# Copy source dir` section, add `COPY <content-dir>/ <content-dir>/` for each content directory in `JFME_CONTENT_DIRS`
+
+### `views.py` :
+- In the `get_object` method of `IndexView`, set the `self.kwargs["slug"]` to the slug of your index page which is sent at the root of your site
+
+## Usage
+
+Each directory defined in `JFME_CONTENT_DIRS` has the following structure :
+```
+Content-dir/
+    |-- templates/
+    |   |-- django/
+    |   |   |-- blocks/
+    |   |   |-- widgets/
+    |   |-- jinja2/
+    |       |-- blocks/
+    |       |-- widgets/
+    |       |-- base.html
+    |       |-- page.html
+    |       |-- post.html
+    |       |-- sitemap.html
+    |-- pages/
+    |-- posts/
+    |-- static/
+```
+
+### Templates :
+For Django engine, see https://docs.djangoproject.com/en/5.0/ref/templates/language/ \
+For Jinja2 engine, see https://jinja.palletsprojects.com/en/2.11.x/templates/
+
+`page.html` and `post.html` are the firsts templates called to render a page or a post. By default, they extend the `base.html` template.
+
+### Pages :
+Pages contain the content of each web page of the site at url `pages/<slug>.html`. They are `.md` files and are structured in 3 sections separated by a line starting with `---` :
+
+- **Metadata** provide some informartion about the page (description, language...). Each metadata is a key, some spaces, and a value. The `title` metadata is required for all pages. Other metadata can be useful, like `slug`, `lang`, `template_engine` or `og:<key>` (open graph). Metadata are accessible by a dictionary in `object.metadata` in templates.
+- **Data** is a section which contains a JSON text. It is accessible by `object.data` in templates.
+- **Body** : It is the concrete content of the page, that can be html or template content. For instance, it is possible to use widgets or blocks in this section. It is accessible by `object.content` in templates.
+
+### Posts :
+Like pages, they contain the content of each post at url `posts/<slug>.html`. They require an additional metadata `date` in ISO format
+
+### Static :
+This directory is for the static content, like images, CSS and JavaScript files ... \
+It is accessible in templates by the Jinja or Django `static` function. \
+See the [Django doc](https://docs.djangoproject.com/en/5.0/howto/static-files/#configuring-static-files) for static files, or the [Jinja2 version](https://docs.djangoproject.com/en/5.0/topics/templates/#module-django.template.backends.django).
+
 ## Others
 
-This repo is a fork of https://github.com/jtremesay/jssg.git for algoo websites use cases.
+JFM-Engine is a friendly fork of [JSSG](https://github.com/jtremesay/jssg/) made in agreement with the JSSG developer because of different goals. \
+See the [issue #21](https://github.com/jtremesay/jssg/issues/21).

docker-compose.yml

@@ -15,7 +15,7 @@
 version: "3.8"
 services:
   jtremesay:
-    image: "killruana/jtremesay.org:main"
+    image: "jssg"
     ports:
       - 8003:80
     networks:

jssg/models.py

@@ -36,7 +36,7 @@ class Document:
     """
 
     # Default dir to search document
-    BASE_DIR = settings.JSSG_CONTENT_DIR
+    BASE_DIR = settings.JFME_CONTENT_DIRS
 
     def __init__(self, content: str, **metadata: Mapping[str, str]) -> None:
         """Create a new document.
@@ -220,7 +220,7 @@ def load_glob(
 class Page(Document):
     """A webpage, with a title and some content."""
 
-    BASE_DIR = settings.JSSG_PAGES_DIR
+    BASE_DIR = settings.JFME_PAGES_DIRS
 
     def __init__(self, content: str, **metadata) -> None:
         """Create a new page.
@@ -254,7 +254,7 @@ def get_pages(cls):
 class Post(Page):
     """A webblog post."""
 
-    BASE_DIR = settings.JSSG_POSTS_DIR
+    BASE_DIR = settings.JFME_POSTS_DIRS
 
     def __init__(self, content: str, **metadata) -> None:
         """Create a new post.
@@ -277,7 +277,7 @@ def get_posts(cls):
         return ({"slug": p.slug} for p in Post.load_glob())
 
 class Sitemap :
-    BASE_DIR = settings.JSSG_PAGES_DIR + settings.JSSG_POSTS_DIR
-    domain = settings.JSSG_DOMAIN
+    BASE_DIR = settings.JFME_PAGES_DIRS + settings.JFME_POSTS_DIRS
+    domain = settings.JFME_DOMAIN
     pages_slugs = [p["slug"] for p in Page.get_pages()]
     posts_slugs = [p["slug"] for p in Post.get_posts()]

jssg/settings.py

@@ -46,12 +46,12 @@
 runserver.default_addr = '127.0.0.1'
 
 # JSSG
-JSSG_DOMAIN = "https://www.galae.net"
-JSSG_CONTENT_DIR = [BASE_DIR / "content"] + [BASE_DIR / "galae-content"] + [BASE_DIR / "common-content"]
-JSSG_PAGES_DIR = [path / "pages" for path in JSSG_CONTENT_DIR]
-JSSG_POSTS_DIR = [path / "posts" for path in JSSG_CONTENT_DIR]
-JSSG_TEMPLATES_DIR = [path / "templates" for path in JSSG_CONTENT_DIR]
-JSSG_STATIC_DIR = [path / "static" for path in JSSG_CONTENT_DIR]
+JFME_DOMAIN = "https://www.galae.net"
+JFME_CONTENT_DIRS = [BASE_DIR / "content"] + [BASE_DIR / "galae-content"] + [BASE_DIR / "common-content"]
+JFME_PAGES_DIRS = [path / "pages" for path in JFME_CONTENT_DIRS]
+JFME_POSTS_DIRS = [path / "posts" for path in JFME_CONTENT_DIRS]
+JFME_TEMPLATES_DIRS = [path / "templates" for path in JFME_CONTENT_DIRS]
+JFME_STATIC_DIRS = [path / "static" for path in JFME_CONTENT_DIRS]
 
 
 
@@ -77,15 +77,15 @@
 TEMPLATES = [
     {
         "BACKEND": "django.template.backends.jinja2.Jinja2",
-        "DIRS": [path / "jinja2" for path in JSSG_TEMPLATES_DIR],
+        "DIRS": [path / "jinja2" for path in JFME_TEMPLATES_DIRS],
         "APP_DIRS": True,
         "OPTIONS": {
             "environment": "jssg.jinja2.environment"
         },
     },
     {
         "BACKEND": "django.template.backends.django.DjangoTemplates",
-        "DIRS": [path / "django" for path in JSSG_TEMPLATES_DIR],
+        "DIRS": [path / "django" for path in JFME_TEMPLATES_DIRS],
         "APP_DIRS": True,
         "OPTIONS": {
             "context_processors": [
@@ -142,7 +142,7 @@
 
 DIST_DIR = BASE_DIR / "dist"
 STATIC_ROOT = BASE_DIR / "static"
-STATICFILES_DIRS = JSSG_STATIC_DIR
+STATICFILES_DIRS = JFME_STATIC_DIRS
 
 # Default primary key field type
 # https://docs.djangoproject.com/en/5.0/ref/settings/#default-auto-field