From 75f48ac62c2619258efc70a5496de0cff4d58d2d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment?= Date: Mon, 1 Jul 2024 16:46:40 +0200 Subject: [PATCH 1/4] Add config and usage documentation in README --- README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 58 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ade25ff..bba8f84 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,8 @@ Today, it's a django app that can generate a static website with Vite & Typescri ## 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 @@ -48,6 +48,62 @@ $ docker build -t jssg . $ sudo docker run -p 8080:80 jssg:latest ``` +## Config + +### `settings.py` : +For django settings, see https://docs.djangoproject.com/en/5.0/ref/settings/ + +Otherwise, you have to configure the following settings : +- `JSSG_DOMAIN` : the domain name of your website, for example `"https://www.example.com"` (used in sitemap file) +- `JSSG_CONTENT_DIR` : a list of directories where look for the site content + +### `Dockerfile` : +- In the `# Copy source dir` section, add `COPY / /` for each content directory in `JSSG_CONTENT_DIR` + +### `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 `JSSG_CONTENT_DIR` 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 : https://docs.djangoproject.com/en/5.0/ref/templates/language/ \ +For Jinja2 engine : 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. In these templates, the content of a page is accessible by `object.content`. By default, they extend the `base.html` template. + +### Pages : +Pages contain the content of each web page of the site at `pages/.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. `slug`, `lang`, `engine` or open graph metadata can also be useful. 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 example, it is possible to use widgets or blocks in this section. + +### Posts : +Like pages, they contain the content of each post at `posts/.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 `static` function. + ## Others This repo is a fork of https://github.com/jtremesay/jssg.git for algoo websites use cases. From bb9b8883844aefa24298e41aa53bc75efabe492a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment?= Date: Fri, 5 Jul 2024 16:10:09 +0200 Subject: [PATCH 2/4] Improve documentation --- README.md | 33 ++++++++++++++++----------------- docker-compose.yml | 2 +- 2 files changed, 17 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index bba8f84..283dcaf 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,5 @@ -# JSSG - Jtremesay's Static Site Generator +# JFM-Engine -[![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). Today, it's a django app that can generate a static website with Vite & Typescript integration. @@ -44,8 +41,9 @@ $ ./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 @@ -54,8 +52,8 @@ $ sudo docker run -p 8080:80 jssg:latest For django settings, see https://docs.djangoproject.com/en/5.0/ref/settings/ Otherwise, you have to configure the following settings : -- `JSSG_DOMAIN` : the domain name of your website, for example `"https://www.example.com"` (used in sitemap file) -- `JSSG_CONTENT_DIR` : a list of directories where look for the site content +- `JSSG_DOMAIN` : the domain name of your website, for instance `"https://www.example.com"` (used in sitemap file) +- `JSSG_CONTENT_DIR` : a list of directories where to look for the site content ### `Dockerfile` : - In the `# Copy source dir` section, add `COPY / /` for each content directory in `JSSG_CONTENT_DIR` @@ -85,24 +83,25 @@ Content-dir/ ``` ### Templates : -For Django engine : https://docs.djangoproject.com/en/5.0/ref/templates/language/ \ -For Jinja2 engine : https://jinja.palletsprojects.com/en/2.11.x/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. In these templates, the content of a page is accessible by `object.content`. By default, they extend the `base.html` template. +`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 `pages/.html`. They are `.md` files and are structured in 3 sections separated by a line starting with `---` : +Pages contain the content of each web page of the site at url `pages/.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. `slug`, `lang`, `engine` or open graph metadata can also be useful. Metadata are accessible by a dictionary in `object.metadata` in templates. +- **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`, `engine` or `og:` (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 example, it is possible to use widgets or blocks in this section. +- **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 `posts/.html`. They require an additional metadata `date` in ISO format. +Like pages, they contain the content of each post at url `posts/.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 `static` function. +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 diff --git a/docker-compose.yml b/docker-compose.yml index cb7f787..71eaf4f 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -15,7 +15,7 @@ version: "3.8" services: jtremesay: - image: "killruana/jtremesay.org:main" + image: "jssg" ports: - 8003:80 networks: From a8599d2cb444b9bbf1848e043f2c61bd5bc306c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment?= Date: Fri, 5 Jul 2024 16:59:59 +0200 Subject: [PATCH 3/4] rename engine metadata to template_engine --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 283dcaf..05a14f1 100644 --- a/README.md +++ b/README.md @@ -91,7 +91,7 @@ For Jinja2 engine, see https://jinja.palletsprojects.com/en/2.11.x/templates/ ### Pages : Pages contain the content of each web page of the site at url `pages/.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`, `engine` or `og:` (open graph). Metadata are accessible by a dictionary in `object.metadata` in templates. +- **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:` (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. From 0a240f7dda2b09f5a733977f9c92ef9f2b636825 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment?= Date: Mon, 8 Jul 2024 12:54:35 +0200 Subject: [PATCH 4/4] Add reference of JSSG in readme Rename settings --- README.md | 12 ++++++------ jssg/models.py | 10 +++++----- jssg/settings.py | 18 +++++++++--------- 3 files changed, 20 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 05a14f1..9bd08df 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ # JFM-Engine - Today, it's a django app that can generate a static website with Vite & Typescript integration. ## Bootstrap @@ -52,18 +51,18 @@ $ sudo docker compose up For django settings, see https://docs.djangoproject.com/en/5.0/ref/settings/ Otherwise, you have to configure the following settings : -- `JSSG_DOMAIN` : the domain name of your website, for instance `"https://www.example.com"` (used in sitemap file) -- `JSSG_CONTENT_DIR` : a list of directories where to look for the site content +- `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 / /` for each content directory in `JSSG_CONTENT_DIR` +- In the `# Copy source dir` section, add `COPY / /` 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 `JSSG_CONTENT_DIR` has the following structure : +Each directory defined in `JFME_CONTENT_DIRS` has the following structure : ``` Content-dir/ |-- templates/ @@ -105,4 +104,5 @@ See the [Django doc](https://docs.djangoproject.com/en/5.0/howto/static-files/#c ## 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). diff --git a/jssg/models.py b/jssg/models.py index a41f524..e3e1156 100644 --- a/jssg/models.py +++ b/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. @@ -222,7 +222,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. @@ -256,7 +256,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. @@ -279,7 +279,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()] diff --git a/jssg/settings.py b/jssg/settings.py index 2d1fd0c..830599b 100644 --- a/jssg/settings.py +++ b/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,7 +77,7 @@ 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" @@ -85,7 +85,7 @@ }, { "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