Add .gitignore and initial README.md for project setup

2026-05-02 12:32:37 +02:00
commit 559a6e4c56
2 changed files with 60 additions and 0 deletions
@@ -0,0 +1,12 @@
+# instruction files
+.github/instructions/
+
+# vscode settings
+.vscode/
+
+# python virtual environment
+.venv/
+
+# python cache
+__pycache__/
+*.pyc
@@ -0,0 +1,48 @@
+# allucanget.biz website version 5
+
+This repository contains the source for the allucanget.biz website version 5.
+The current build workflow is driven by `main.py`, which renders Jinja2 templates located in the `templates/` folder and writes minified HTML output to the `html/` directory.
+
+## Current build workflow (what `main.py` does)
+
+- Loads configuration constants at the top of `main.py`:
+  - `TEMPLATE_DIR = 'templates'`
+  - `OUTPUT_DIR = 'html'`
+  - `NAV` and `PAGES` dictionaries that describe navigation and per-page metadata from json files located in `docs/`.
+- Uses Jinja2 `Environment(loader=FileSystemLoader(TEMPLATE_DIR))` to render templates.
+- For each template file (all `.html` files in `templates/` that do not start with `_`):
+  - If the template file has an entry in `PAGES`, it uses that page's `page_title`, `page_subtitle`, `page_cta`, `page_cta_url`, and `meta` values to populate the Jinja context.
+  - It sets the `active` flag in the `NAV` structure so templates can render an active navigation item.
+  - Renders the template with the navigation and page context.
+  - Runs a `minify_html` function on the rendered HTML to remove comments and extra whitespace.
+  - Writes the resulting HTML to `html/<template_name>`.
+- After rendering all pages, `main.py` will attempt to minify CSS and JS in the generated `html/css` and `html/js` folders using `css_minifier()` and `js_minifier()`, which rely on simple regex-based minifiers (`minify_css` and `minify_js`).
+
+## Where to find things
+
+- Templates: `templates/` (files like `index.html`, `services.html`, etc.)
+- Generated output: `html/` (created by `main.py`)
+- Source Markdown content (converted in this project): `docs/en/*.md` (there are `index.md`, `services.md`, `coaching.md` already)
+- Assets: `html/css/`, `html/js/`, `html/img/` (expected to be copied/available for the site)
+
+## How to run
+
+1. Create a Python virtual environment and install dependencies. At minimum you need `jinja2`. If you plan to add Markdown rendering, also install a Markdown library such as `markdown` or `markdown2`.
+
+2. Run the build script:
+
+   ```bash
+   python main.py
+   ```
+
+3. The script will generate rendered HTML files under `html/` and attempt to minify CSS/JS in `html/css` and `html/js`.
+
+## Notes & caveats
+
+- The minifiers are simple regex-based helpers. They work for basic minification but are not a full replacement for production-grade tools (e.g., cssnano, terser, html-minifier). Use with caution.
+- `main.py` currently renders Jinja templates and does not yet treat `docs/en/*.md` as first-class content sources. The `docs/en` markdown files were added to start migrating content to Markdown, but `main.py` needs to be extended to load and render those Markdown files automatically (see `TODO.md` for a planned approach).
+- The script expects `templates/` files that may include Jinja blocks, partials (files starting with `_`), and assets referenced by relative paths. Make sure asset paths are present in the output directory or copied during your deploy process.
+
+## Contact
+
+For questions about this build flow or to request changes, update `TODO.md` with the requested enhancements or open an issue in the project.