From d5a9b7f2c1938b2c4015ea8a36702e029d807bbb Mon Sep 17 00:00:00 2001 From: Paulo Ribeiro Date: Fri, 17 Apr 2026 10:03:12 +0100 Subject: [PATCH 1/4] toolchain: Initialize Pelican --- .gitignore | 4 ++ Makefile | 80 +++++++++++++++++++++++++ pelicanconf.py | 32 ++++++++++ publishconf.py | 22 +++++++ tasks.py | 158 +++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 296 insertions(+) create mode 100644 Makefile create mode 100644 pelicanconf.py create mode 100644 publishconf.py create mode 100644 tasks.py diff --git a/.gitignore b/.gitignore index b7faf40..dfcba97 100644 --- a/.gitignore +++ b/.gitignore @@ -205,3 +205,7 @@ cython_debug/ marimo/_static/ marimo/_lsp/ __marimo__/ + +# Pelican +output/ +.cache/ diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..5e57b4d --- /dev/null +++ b/Makefile @@ -0,0 +1,80 @@ +PY?= +PELICAN?=pelican +PELICANOPTS= + +BASEDIR=$(CURDIR) +INPUTDIR=$(BASEDIR)/content +OUTPUTDIR=$(BASEDIR)/output +CONFFILE=$(BASEDIR)/pelicanconf.py +PUBLISHCONF=$(BASEDIR)/publishconf.py + +GITHUB_PAGES_BRANCH=gh-pages +GITHUB_PAGES_COMMIT_MESSAGE=Generate Pelican site + + +DEBUG ?= 0 +ifeq ($(DEBUG), 1) + PELICANOPTS += -D +endif + +RELATIVE ?= 0 +ifeq ($(RELATIVE), 1) + PELICANOPTS += --relative-urls +endif + +SERVER ?= "0.0.0.0" + +PORT ?= 0 +ifneq ($(PORT), 0) + PELICANOPTS += -p $(PORT) +endif + + +help: + @echo 'Makefile for a pelican Web site ' + @echo ' ' + @echo 'Usage: ' + @echo ' make html (re)generate the web site ' + @echo ' make clean remove the generated files ' + @echo ' make regenerate regenerate files upon modification ' + @echo ' make publish generate using production settings ' + @echo ' make serve [PORT=8000] serve site at http://localhost:8000' + @echo ' make serve-global [SERVER=0.0.0.0] serve (as root) to $(SERVER):80 ' + @echo ' make devserver [PORT=8000] serve and regenerate together ' + @echo ' make devserver-global regenerate and serve on 0.0.0.0 ' + @echo ' make github upload the web site via gh-pages ' + @echo ' ' + @echo 'Set the DEBUG variable to 1 to enable debugging, e.g. make DEBUG=1 html ' + @echo 'Set the RELATIVE variable to 1 to enable relative urls ' + @echo ' ' + +html: + "$(PELICAN)" "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS) + +clean: + [ ! -d "$(OUTPUTDIR)" ] || rm -rf "$(OUTPUTDIR)" + +regenerate: + "$(PELICAN)" -r "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS) + +serve: + "$(PELICAN)" -l "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS) + +serve-global: + "$(PELICAN)" -l "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS) -b $(SERVER) + +devserver: + "$(PELICAN)" -lr "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS) + +devserver-global: + "$(PELICAN)" -lr "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS) -b 0.0.0.0 + +publish: + "$(PELICAN)" "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(PUBLISHCONF)" $(PELICANOPTS) + +github: publish + ghp-import -m "$(GITHUB_PAGES_COMMIT_MESSAGE)" -b $(GITHUB_PAGES_BRANCH) "$(OUTPUTDIR)" --no-jekyll + git push origin $(GITHUB_PAGES_BRANCH) + + +.PHONY: html help clean regenerate serve serve-global devserver devserver-global publish github diff --git a/pelicanconf.py b/pelicanconf.py new file mode 100644 index 0000000..bf9d588 --- /dev/null +++ b/pelicanconf.py @@ -0,0 +1,32 @@ +import attila + +AUTHOR = 'paulo ribeiro' +SITENAME = 'd i f f r a c t i o n' +SITEURL = "" + +PATH = "content" + +TIMEZONE = 'Europe/Lisbon' + +DEFAULT_LANG = 'en' + +# Feed generation is usually not desired when developing +FEED_ALL_ATOM = None +CATEGORY_FEED_ATOM = None +TRANSLATION_FEED_ATOM = None +AUTHOR_FEED_ATOM = None +AUTHOR_FEED_RSS = None + +# Theme +THEME = attila.get_path() +HOME_COLOR = '#222222' # fallback header colour when no cover image is set + +# Social +SOCIAL = ( + ('github', 'https://github.com/prcr'), +) + +DEFAULT_PAGINATION = False + +# Uncomment following line if you want document-relative URLs when developing +# RELATIVE_URLS = True diff --git a/publishconf.py b/publishconf.py new file mode 100644 index 0000000..51e0f9c --- /dev/null +++ b/publishconf.py @@ -0,0 +1,22 @@ +# This file is only used if you use `make publish` or +# explicitly specify it as your config file. + +import os +import sys + +sys.path.append(os.curdir) +from pelicanconf import * + +# If your site is available via HTTPS, make sure SITEURL begins with https:// +SITEURL = "https://diffraction.pt/blog" +RELATIVE_URLS = False + +FEED_ALL_ATOM = "feeds/all.atom.xml" +CATEGORY_FEED_ATOM = "feeds/{slug}.atom.xml" + +DELETE_OUTPUT_DIRECTORY = True + +# Following items are often useful when publishing + +# DISQUS_SITENAME = "" +# GOOGLE_ANALYTICS = "" diff --git a/tasks.py b/tasks.py new file mode 100644 index 0000000..c260d4d --- /dev/null +++ b/tasks.py @@ -0,0 +1,158 @@ +import os +import shlex +import shutil +import sys +import datetime + +from invoke import task +from invoke.main import program +from pelican import main as pelican_main +from pelican.server import ComplexHTTPRequestHandler, RootedHTTPServer +from pelican.settings import DEFAULT_CONFIG, get_settings_from_file + +OPEN_BROWSER_ON_SERVE = True +SETTINGS_FILE_BASE = "pelicanconf.py" +SETTINGS = {} +SETTINGS.update(DEFAULT_CONFIG) +LOCAL_SETTINGS = get_settings_from_file(SETTINGS_FILE_BASE) +SETTINGS.update(LOCAL_SETTINGS) + +CONFIG = { + "settings_base": SETTINGS_FILE_BASE, + "settings_publish": "publishconf.py", + # Output path. Can be absolute or relative to tasks.py. Default: 'output' + "deploy_path": SETTINGS["OUTPUT_PATH"], + # Github Pages configuration + "github_pages_branch": "gh-pages", + "commit_message": f"'Publish site on {datetime.date.today().isoformat()}'", + # Host and port for `serve` + "host": "localhost", + "port": 8000, +} + + +@task +def clean(c): + """Remove generated files""" + if os.path.isdir(CONFIG["deploy_path"]): + shutil.rmtree(CONFIG["deploy_path"]) + os.makedirs(CONFIG["deploy_path"]) + + +@task +def build(c): + """Build local version of site""" + pelican_run("-s {settings_base}".format(**CONFIG)) + + +@task +def rebuild(c): + """`build` with the delete switch""" + pelican_run("-d -s {settings_base}".format(**CONFIG)) + + +@task +def regenerate(c): + """Automatically regenerate site upon file modification""" + pelican_run("-r -s {settings_base}".format(**CONFIG)) + + +@task +def serve(c): + """Serve site at http://$HOST:$PORT/ (default is localhost:8000)""" + + class AddressReuseTCPServer(RootedHTTPServer): + allow_reuse_address = True + + server = AddressReuseTCPServer( + CONFIG["deploy_path"], + (CONFIG["host"], CONFIG["port"]), + ComplexHTTPRequestHandler, + ) + + if OPEN_BROWSER_ON_SERVE: + # Open site in default browser + import webbrowser + + webbrowser.open("http://{host}:{port}".format(**CONFIG)) + + sys.stderr.write("Serving at {host}:{port} ...\n".format(**CONFIG)) + server.serve_forever() + + +@task +def reserve(c): + """`build`, then `serve`""" + build(c) + serve(c) + + +@task +def preview(c): + """Build production version of site""" + pelican_run("-s {settings_publish}".format(**CONFIG)) + +@task +def livereload(c): + """Automatically reload browser tab upon file modification.""" + from livereload import Server + + def cached_build(): + cmd = "-s {settings_base} -e CACHE_CONTENT=true LOAD_CONTENT_CACHE=true" + pelican_run(cmd.format(**CONFIG)) + + cached_build() + server = Server() + theme_path = SETTINGS["THEME"] + watched_globs = [ + CONFIG["settings_base"], + f"{theme_path}/templates/**/*.html", + ] + + content_file_extensions = [".md", ".rst"] + for extension in content_file_extensions: + content_glob = "{}/**/*{}".format(SETTINGS["PATH"], extension) + watched_globs.append(content_glob) + + static_file_extensions = [".css", ".js"] + for extension in static_file_extensions: + static_file_glob = f"{theme_path}/static/**/*{extension}" + watched_globs.append(static_file_glob) + + for glob in watched_globs: + server.watch(glob, cached_build) + + if OPEN_BROWSER_ON_SERVE: + # Open site in default browser + import webbrowser + + webbrowser.open("http://{host}:{port}".format(**CONFIG)) + + server.serve(host=CONFIG["host"], port=CONFIG["port"], root=CONFIG["deploy_path"]) + + +@task +def publish(c): + """Publish to production via rsync""" + pelican_run("-s {settings_publish}".format(**CONFIG)) + c.run( + 'rsync --delete --exclude ".DS_Store" -pthrvz -c ' + '-e "ssh -p {ssh_port}" ' + "{} {ssh_user}@{ssh_host}:{ssh_path}".format( + CONFIG["deploy_path"].rstrip("/") + "/", **CONFIG + ) + ) + +@task +def gh_pages(c): + """Publish to GitHub Pages""" + preview(c) + c.run( + "ghp-import -b {github_pages_branch} " + "-m {commit_message} " + "{deploy_path} -p".format(**CONFIG) + ) + +def pelican_run(cmd): + cmd += " " + program.core.remainder # allows to pass-through args to pelican + pelican_main(shlex.split(cmd)) From c6e6f98bed1956c8db3133657bd45429843eb048 Mon Sep 17 00:00:00 2001 From: Paulo Ribeiro Date: Fri, 17 Apr 2026 10:08:27 +0100 Subject: [PATCH 2/4] clean: Remove Makefile and tasks.py --- Makefile | 80 ---------------------------- tasks.py | 158 ------------------------------------------------------- 2 files changed, 238 deletions(-) delete mode 100644 Makefile delete mode 100644 tasks.py diff --git a/Makefile b/Makefile deleted file mode 100644 index 5e57b4d..0000000 --- a/Makefile +++ /dev/null @@ -1,80 +0,0 @@ -PY?= -PELICAN?=pelican -PELICANOPTS= - -BASEDIR=$(CURDIR) -INPUTDIR=$(BASEDIR)/content -OUTPUTDIR=$(BASEDIR)/output -CONFFILE=$(BASEDIR)/pelicanconf.py -PUBLISHCONF=$(BASEDIR)/publishconf.py - -GITHUB_PAGES_BRANCH=gh-pages -GITHUB_PAGES_COMMIT_MESSAGE=Generate Pelican site - - -DEBUG ?= 0 -ifeq ($(DEBUG), 1) - PELICANOPTS += -D -endif - -RELATIVE ?= 0 -ifeq ($(RELATIVE), 1) - PELICANOPTS += --relative-urls -endif - -SERVER ?= "0.0.0.0" - -PORT ?= 0 -ifneq ($(PORT), 0) - PELICANOPTS += -p $(PORT) -endif - - -help: - @echo 'Makefile for a pelican Web site ' - @echo ' ' - @echo 'Usage: ' - @echo ' make html (re)generate the web site ' - @echo ' make clean remove the generated files ' - @echo ' make regenerate regenerate files upon modification ' - @echo ' make publish generate using production settings ' - @echo ' make serve [PORT=8000] serve site at http://localhost:8000' - @echo ' make serve-global [SERVER=0.0.0.0] serve (as root) to $(SERVER):80 ' - @echo ' make devserver [PORT=8000] serve and regenerate together ' - @echo ' make devserver-global regenerate and serve on 0.0.0.0 ' - @echo ' make github upload the web site via gh-pages ' - @echo ' ' - @echo 'Set the DEBUG variable to 1 to enable debugging, e.g. make DEBUG=1 html ' - @echo 'Set the RELATIVE variable to 1 to enable relative urls ' - @echo ' ' - -html: - "$(PELICAN)" "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS) - -clean: - [ ! -d "$(OUTPUTDIR)" ] || rm -rf "$(OUTPUTDIR)" - -regenerate: - "$(PELICAN)" -r "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS) - -serve: - "$(PELICAN)" -l "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS) - -serve-global: - "$(PELICAN)" -l "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS) -b $(SERVER) - -devserver: - "$(PELICAN)" -lr "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS) - -devserver-global: - "$(PELICAN)" -lr "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(CONFFILE)" $(PELICANOPTS) -b 0.0.0.0 - -publish: - "$(PELICAN)" "$(INPUTDIR)" -o "$(OUTPUTDIR)" -s "$(PUBLISHCONF)" $(PELICANOPTS) - -github: publish - ghp-import -m "$(GITHUB_PAGES_COMMIT_MESSAGE)" -b $(GITHUB_PAGES_BRANCH) "$(OUTPUTDIR)" --no-jekyll - git push origin $(GITHUB_PAGES_BRANCH) - - -.PHONY: html help clean regenerate serve serve-global devserver devserver-global publish github diff --git a/tasks.py b/tasks.py deleted file mode 100644 index c260d4d..0000000 --- a/tasks.py +++ /dev/null @@ -1,158 +0,0 @@ -import os -import shlex -import shutil -import sys -import datetime - -from invoke import task -from invoke.main import program -from pelican import main as pelican_main -from pelican.server import ComplexHTTPRequestHandler, RootedHTTPServer -from pelican.settings import DEFAULT_CONFIG, get_settings_from_file - -OPEN_BROWSER_ON_SERVE = True -SETTINGS_FILE_BASE = "pelicanconf.py" -SETTINGS = {} -SETTINGS.update(DEFAULT_CONFIG) -LOCAL_SETTINGS = get_settings_from_file(SETTINGS_FILE_BASE) -SETTINGS.update(LOCAL_SETTINGS) - -CONFIG = { - "settings_base": SETTINGS_FILE_BASE, - "settings_publish": "publishconf.py", - # Output path. Can be absolute or relative to tasks.py. Default: 'output' - "deploy_path": SETTINGS["OUTPUT_PATH"], - # Github Pages configuration - "github_pages_branch": "gh-pages", - "commit_message": f"'Publish site on {datetime.date.today().isoformat()}'", - # Host and port for `serve` - "host": "localhost", - "port": 8000, -} - - -@task -def clean(c): - """Remove generated files""" - if os.path.isdir(CONFIG["deploy_path"]): - shutil.rmtree(CONFIG["deploy_path"]) - os.makedirs(CONFIG["deploy_path"]) - - -@task -def build(c): - """Build local version of site""" - pelican_run("-s {settings_base}".format(**CONFIG)) - - -@task -def rebuild(c): - """`build` with the delete switch""" - pelican_run("-d -s {settings_base}".format(**CONFIG)) - - -@task -def regenerate(c): - """Automatically regenerate site upon file modification""" - pelican_run("-r -s {settings_base}".format(**CONFIG)) - - -@task -def serve(c): - """Serve site at http://$HOST:$PORT/ (default is localhost:8000)""" - - class AddressReuseTCPServer(RootedHTTPServer): - allow_reuse_address = True - - server = AddressReuseTCPServer( - CONFIG["deploy_path"], - (CONFIG["host"], CONFIG["port"]), - ComplexHTTPRequestHandler, - ) - - if OPEN_BROWSER_ON_SERVE: - # Open site in default browser - import webbrowser - - webbrowser.open("http://{host}:{port}".format(**CONFIG)) - - sys.stderr.write("Serving at {host}:{port} ...\n".format(**CONFIG)) - server.serve_forever() - - -@task -def reserve(c): - """`build`, then `serve`""" - build(c) - serve(c) - - -@task -def preview(c): - """Build production version of site""" - pelican_run("-s {settings_publish}".format(**CONFIG)) - -@task -def livereload(c): - """Automatically reload browser tab upon file modification.""" - from livereload import Server - - def cached_build(): - cmd = "-s {settings_base} -e CACHE_CONTENT=true LOAD_CONTENT_CACHE=true" - pelican_run(cmd.format(**CONFIG)) - - cached_build() - server = Server() - theme_path = SETTINGS["THEME"] - watched_globs = [ - CONFIG["settings_base"], - f"{theme_path}/templates/**/*.html", - ] - - content_file_extensions = [".md", ".rst"] - for extension in content_file_extensions: - content_glob = "{}/**/*{}".format(SETTINGS["PATH"], extension) - watched_globs.append(content_glob) - - static_file_extensions = [".css", ".js"] - for extension in static_file_extensions: - static_file_glob = f"{theme_path}/static/**/*{extension}" - watched_globs.append(static_file_glob) - - for glob in watched_globs: - server.watch(glob, cached_build) - - if OPEN_BROWSER_ON_SERVE: - # Open site in default browser - import webbrowser - - webbrowser.open("http://{host}:{port}".format(**CONFIG)) - - server.serve(host=CONFIG["host"], port=CONFIG["port"], root=CONFIG["deploy_path"]) - - -@task -def publish(c): - """Publish to production via rsync""" - pelican_run("-s {settings_publish}".format(**CONFIG)) - c.run( - 'rsync --delete --exclude ".DS_Store" -pthrvz -c ' - '-e "ssh -p {ssh_port}" ' - "{} {ssh_user}@{ssh_host}:{ssh_path}".format( - CONFIG["deploy_path"].rstrip("/") + "/", **CONFIG - ) - ) - -@task -def gh_pages(c): - """Publish to GitHub Pages""" - preview(c) - c.run( - "ghp-import -b {github_pages_branch} " - "-m {commit_message} " - "{deploy_path} -p".format(**CONFIG) - ) - -def pelican_run(cmd): - cmd += " " + program.core.remainder # allows to pass-through args to pelican - pelican_main(shlex.split(cmd)) From 72e794dafd7aebef0956bdff39448707aa5b0270 Mon Sep 17 00:00:00 2001 From: Paulo Ribeiro Date: Fri, 17 Apr 2026 10:11:52 +0100 Subject: [PATCH 3/4] fix: Set SITEURL --- pelicanconf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pelicanconf.py b/pelicanconf.py index bf9d588..e33d2dd 100644 --- a/pelicanconf.py +++ b/pelicanconf.py @@ -2,7 +2,7 @@ AUTHOR = 'paulo ribeiro' SITENAME = 'd i f f r a c t i o n' -SITEURL = "" +SITEURL = "https://diffraction.pt/blog" PATH = "content" From c944de67f1e5b3dcf746213bca3ddbbbab6ba2f6 Mon Sep 17 00:00:00 2001 From: Paulo Ribeiro Date: Fri, 17 Apr 2026 10:14:00 +0100 Subject: [PATCH 4/4] fix: Turn off SEO_REPORT --- pelicanconf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pelicanconf.py b/pelicanconf.py index e33d2dd..8a9a1c8 100644 --- a/pelicanconf.py +++ b/pelicanconf.py @@ -21,6 +21,9 @@ THEME = attila.get_path() HOME_COLOR = '#222222' # fallback header colour when no cover image is set +# Plugins +SEO_REPORT = False # suppress seo_report.html generation + # Social SOCIAL = ( ('github', 'https://github.com/prcr'),