nibula 2.4.3 → 2.4.4

package/docs/Components.md

@@ -1,236 +0,0 @@
-# Nunjucks (HTML) Components
-
-## What is Nunjucks
-
-Nunjucks (`.njk`) is an HTML file that supports logic like variables, `if` statements, and `for` loops. It can extend a base layout and include other `.njk` components
-
-## Create a component
-
-Create a new `.njk` file anywhere inside `src/frontend/components/`. You can organize them into subfolders freely
-
-```
-src/frontend/components/
-├── global/
-│   ├── header.njk
-│   └── footer.njk
-├── not-found.njk
-├── welcome.njk
-```
-
-## Include a component
-
-Components are included in the page that renders them. Open the page's file in `src/frontend/routes/` and write the includes in its body
-
-### example-page.njk <small>(`src/frontend/routes/`)</small>
-
-```js
----
-title: "examplePage"
-permalink: "/example-page/"
-layout: base.njk
----
-
-{% include "example-component-1.njk" %}
-{% include "subfolder/example-component-2.njk" %}
-```
-
-Components render in the order you list them. If a component lives in a subfolder, specify the relative path accordingly
-
-Paths are resolved from `src/frontend/components/`, so you never write that part — `"welcome.njk"`, not `"components/welcome.njk"`
-
-> ⚠️ If you move or delete a component, update every route that includes it or the build will fail
-
-Writing HTML directly in the route works too, and is perfectly fine for a short page. Components are the recommendation when there is something to reuse or when a page grows past a screenful — not a rule
-
-## Nest components
-
-A component can include other components. This is useful for breaking complex sections into smaller, reusable pieces.
-
-### exampleComponent.njk
-```html
-<section class="hero">
-  {% include "hero/hero-title.njk" %}
-  {% include "hero/hero-button.njk" %}
-</section>
-```
-
-> The same path rules apply: if the included component is in a subfolder, specify the full relative path.
-
-## Markdown files
-
-### What is Markdown
-
-Markdown (`.md`) is a way to write formatted text without HTML tags. You write
-`**bold**` instead of `<strong>bold</strong>`, and a line starting with `-`
-becomes a list item. For a page that is mostly text — an article, a privacy
-policy, a changelog — it is much faster than writing the markup by hand.
-
-### Write the file
-
-Create a `.md` file in `src/frontend/components/`, next to your `.njk` ones.
-
-#### article.md <small>(`src/frontend/components/`)</small>
-
-```markdown
-## Section title
-
-Regular paragraph text. **Bold** and *italic* work as usual.
-
-- First item
-- Second item
-```
-
-### Show it in a page
-
-Open the page's file in `src/frontend/routes/` and add this line to its body:
-
-```html
-<article class="markdown-body">
-    {% renderFile "article.md" | markdownPath, { site: site }, "md" %}
-</article>
-```
-
-Four parts to it:
-
-| Part | What it does |
-|---|---|
-| `class="markdown-body"` | the wrapper that applies the Markdown styling — without it your content renders unstyled |
-| `renderFile` | turns the Markdown into HTML and puts it in the page |
-| `markdownPath` | fills in the `src/frontend/components/` part of the path for you |
-| `{ site: site }` | hands the file your site settings — see below |
-| `"md"` | specifies that the rendering should be done as Markdown, ignoring the njk engine associated by default with the file extension |
-
-Subfolders work the same way as with components:
-`"legal/privacy.md" | markdownPath`
-
-### Why `{ site: site }`
-
-A `.md` file can use site values, exactly like a component:
-
-```markdown
-Welcome to {{ site.title }}
-```
-
-But a Markdown file does not automatically see them. Anything the file needs has
-to be listed in the curly braces:
-
-```js
-{% renderFile "article.md" | markdownPath, { site: site, pages: pages } %}
-```
-
-If you forget, nothing breaks — the value simply comes out empty. So if a
-`{{ site.something }}` disappears from your page, this is why.
-
-### Extras you get for free
-
-**Links to a section.** Every `##` and `###` heading gets an anchor, so you can
-link straight to it: `yoursite.com/my-page/#section-title`.
-
-**CSS classes.** Markdown produces plain HTML with no classes, so your framework's
-styling doesn't reach it. Add a class in curly braces after the element:
-
-```markdown
-## Section title {.text-center}
-```
-
-> ⚠️ If the `.md` file is missing or the name is misspelled, the build stops with
-> an error. That is on purpose: silently skipping content you asked for is worse.
-
-## Global components
-
-Header and footer live in `src/frontend/components/global/` and are automatically included in every page via `base.njk`. Edit them to change the site-wide layout
-
-## Custom layouts
-
-`base.njk` is the default layout, but it isn't the only one you can have. Any
-`.njk` file in `src/frontend/layouts/` is a layout, and each route picks its own.
-
-The usual reason is a page that doesn't fit the standard shell: a landing page
-with no header or footer, a full-screen login, a "coming soon" holding page.
-
-Copy `base.njk`, rename it, and change only what you need — that way you keep the
-head, the SEO tags and the CSS/JS wiring, which is the part you don't want to
-rewrite:
-
-```
-src/frontend/layouts/
-├── base.njk
-└── custom.njk
-```
-
-### custom.njk <small>(`src/frontend/layouts/`)</small>
-
-Same as `base.njk`, without the two global includes:
-
-```html
-<body>
-    <main>
-        {{ content | safe }}
-    </main>
-</body>
-```
-
-Then point the route at it:
-
-### landing.njk <small>(`src/frontend/routes/`)</small>
-
-```js
----
-title: "landing"
-permalink: "/landing/"
-layout: custom.njk
----
-```
-
-Paths are resolved from `src/frontend/layouts/`, so you write `"custom.njk"`, not
-`"layouts/custom.njk"` — the same rule as components.
-
-> ⚠️ A layout you copy is a copy: a later fix to `base.njk` won't reach it. Keep
-> the differences to the minimum, and check your custom layouts when you change
-> something in the head.
-
-## Site data in components
-
-All values defined in `src/frontend/data/site.json` are globally available in every component via `{{ site.* }}`
-
-### site.json <small>(`src/frontend/data/`)</small>
-```json
-{
-  "site_name": "Site name",
-  "title": "Site title",
-  "description": "Site description",
-  "keywords": "keyword1, keyword2, keyword3",
-  "domain": "yoursite.com",
-  "url": "https://yoursite.com",
-  "lang": "en",
-  "author": "Name and surname",
-  "logo": "/assets/brand/logo.svg",
-  "legal": {
-    "privacy": "",
-    "cookie": "",
-    "terms": "",
-    "copyright": {
-      "year": "2026",
-      "text": "All rights reserved."
-    }
-  }
-}
-```
-
-`legal.privacy`, `legal.cookie` and `legal.terms` hold the URLs of your legal pages — the footer links to them. See **Head & SEO** DOC file for what every field does
-
-### Usage in any `.njk` file
-```html
-<p>{{ site.title }}</p>
-<a href="{{ site.legal.privacy }}">Privacy Policy</a>
-<img src="{{ site.logo }}" alt="{{ site.title }}">
-```
-
-> In a `.md` file rendered with `renderFile`, these values only work if you passed
-> `site` in the curly braces — see *Why `{ site: site }`* above.
-
-## Your own data files
-
-`site.json` isn't special: **any** `.json` file you drop in `src/frontend/data/` becomes a global variable, and the variable takes the name of the file.
-
-Create `test.json`, put anything you want inside it, and every key is reachable as `test.yourKey` — no import, no configuration, no restart.

package/docs/Creating pages.md

@@ -1,52 +0,0 @@
-# Creating Pages
-
-> Examples use JavaScript, but everything applies equally to TypeScript. The only difference is the file extension (`.ts` instead of `.js`), that imports do **not** include the extension, and that paths use `src/frontend/ts/` instead of `src/frontend/js/`.
-
-The recommended way is via the **Assistant CLI**
-
-## What gets created
-For a page named `my-page`:
-
-| File | Purpose |
-|---|---|
-| `src/frontend/routes/my-page.njk` | Template with front matter |
-| `src/frontend/scss/pages/myPage.scss` | Imports framework + modules |
-| `src/frontend/js/pages/myPage.js` | Imports JS/TS modules |
-
-It also adds a stub entry in `src/frontend/data/pages.json` for the page's SEO and CDN links — fill it in as described in the **Head & SEO** DOC file.
-
-## Adding content
-
-The route is created empty, with two commented examples: one for including a
-`.njk` component, one for rendering a `.md` file. Uncomment the one you need or
-write your HTML directly in the body — see the **Components** DOC file.
-
-## URL and title
-
-The URL is the kebab-case name (`/my-page/`). The `title` in the front matter is camelCase (`myPage`) and is used internally to load the correct CSS and JS files, and to look up the page's record in `pages.json` — do not change it.
-
-## Layout
-
-`layout` decides the HTML skeleton the page is rendered into. New pages get `base.njk`, which brings the head, the SEO tags, the header and the footer.
-
-A page that needs a different shell — a landing page with no header, for instance — points at a layout of its own. See **Components** DOC file, *Custom layouts*.
-
-## Subpages (nested URLs)
-
-To create a URL like `domain.it/about/team`, edit the `permalink` in `src/frontend/routes/team.njk` and add the parent segment before the final slash:
-
-```js
----
-title: "team"
-permalink: "/about/team/"
-layout: base.njk
----
-```
-
-The parent path (`about`) does **not** need to exist as a real page — it's just a URL prefix. Only the last segment (`team`) must match the filename and the `title` in the front matter.
-
-| Goal URL | permalink value | File |
-|---|---|---|
-| `/team/` | `/team/` | `routes/team.njk` |
-| `/about/team/` | `/about/team/` | `routes/team.njk` |
-| `/company/about/team/` | `/company/about/team/` | `routes/team.njk` |

package/docs/Deploy.md

@@ -1,279 +0,0 @@
-# Deploy
-
-Nibula builds your finished site into a folder called `out`. Publishing means
-copying that folder onto a web server so people can reach it.
-
-How you do that depends on two things: **where** you are publishing, and **which
-backend** you picked when you created the project (see `docs/Backend.md`).
-
-## Start here
-
-If you don't know which case you are in, answer this first:
-
-**Did you choose the PHP backend or the Node backend?**
-
-- **PHP** → almost anywhere works, including cheap hosting plans. Jump to
-  *Shared hosting* or *Windows hosting*.
-- **Node** → you need a server you control. Jump to *Your own server*.
-- **No `/api` endpoints at all?** Your site is fully static. Anything works,
-  including free hosting like Netlify or GitHub Pages.
-
-## Why the backend decides everything
-
-The two backends run in completely different ways, and this is the one thing
-worth understanding before you pick a host.
-
-**PHP** runs **once per visit**. A request arrives, the web server starts PHP,
-PHP answers, PHP exits. Nothing stays running, so there is nothing to look after.
-
-**Node is itself a server**. It is a program that must stay running all the time,
-listening in the background, while the web server forwards `/api` requests to it.
-Somebody has to start that program and restart it if the machine reboots or the
-program crashes.
-
-That is why **cheap shared hosting cannot run the Node backend**. On plans like
-Aruba or cPanel you upload files into a folder and that's all you can do — there
-is no way to start a program and keep it alive. If that's your host, choose PHP.
-It isn't a limitation of Nibula.
-
-> **Shared hosting** means a plan where you share a server with other customers
-> and only get a folder to upload into. **A VPS** is a whole machine that is
-> yours, where you can install and run whatever you want.
-
-## Where you can publish
-
-| Target | Frontend | PHP backend | Node backend |
-|---|---|---|---|
-| Shared hosting (Apache — Aruba, cPanel) | ✅ | ✅ | ❌ no program can stay running |
-| Windows hosting (IIS) | ✅ | ✅ | ⚠️ only with the ARR module |
-| Your own VPS (Nginx on Ubuntu) | ✅ | ✅ | ✅ |
-| Static hosting (Netlify, Vercel, GitHub Pages) | ✅ | ❌ | ❌ |
-
-Static hosting serves files and nothing else. Perfect if your site has no `/api`
-endpoints, unusable if it does.
-
-## What you need
-
-**PHP backend:** a host with PHP support, and Composer to install the backend's
-dependencies.
-
-**Node backend:** Node.js 18 or newer, and command-line access to the server so
-you can start the backend program.
-
-## Editing the server config
-
-Every server needs a configuration file telling it how to behave — which page to
-show on a 404, which files to keep private, where to send `/api` requests. Nibula
-writes these for you.
-
-`.htaccess` (Apache) and `web.config` (IIS) are already inside `out`, ready to
-upload. To change a rule, edit the original in `src/frontend/hosting/` — anything
-you change directly inside `out` is erased the next time you build.
-
-`nginx.conf` is different. It sits in your project root and is **not** copied into
-`out`, because Nginx does not read config files from the site folder. You install
-it on the server yourself, as described below.
-
----
-
-## Shared hosting (Apache)
-
-Upload **the contents of `out`** — not the folder itself — into your web root.
-Depending on the host it is called `htdocs`, `public_html` or `www`.
-
-That's it. `.htaccess` is already in there and Apache reads it automatically:
-folder listings are off, errors show your `/404.html`, sensitive files are
-blocked, the backend source is sealed off, and `/api/*` is routed.
-
-**How `/api` gets routed:** if the server has a module called `mod_proxy`, `/api`
-is forwarded to Node. If it doesn't — the usual case on shared hosting — `/api`
-goes to PHP instead. To force PHP on a server that does have `mod_proxy`, comment
-out the `mod_proxy` block in `.htaccess`.
-
-## Windows hosting (IIS)
-
-Same as above: upload the contents of `out`. `web.config` is already there and
-read automatically.
-
-**How `/api` gets routed:** to PHP, by default. To use Node instead, uncomment
-the `ApiToNode` rule in `web.config` and delete `ApiToPhp`. This only works if
-the server has the ARR and URL Rewrite modules with proxying turned on — which
-means a server you control, not shared hosting.
-
-> ⚠️ **If you chose Node and your host has no ARR** (Aruba and most Windows
-> shared hosting), do **not** upload the `backend` folder. Without it the static
-> site works fine and `/api/*` simply shows your `404.html`. Upload it and every
-> `/api` request returns an empty 404 instead, because IIS sends the request to
-> the PHP front controller — a file a Node project doesn't have.
-
----
-
-## Your own server (Nginx on a VPS)
-
-Nginx doesn't read config files from the site folder: the whole site is described
-in one file kept elsewhere on the machine. Nibula ships that file, ready to use,
-as `nginx.conf` in your project root.
-
-It **handles both backends with no edits**: `/api` goes to Node, and if Node
-isn't running the request falls through to PHP automatically.
-
-Upload the contents of `out` to `/var/www/SITE_FOLDER`, then work through the
-steps below.
-
-### 1. Fill in the placeholders
-
-Open `nginx.conf` on your computer and replace these four words with your own
-values:
-
-| Placeholder | What to put there |
-|---|---|
-| `YOUR_DOMAIN` | your domain — appears twice, once for port 80 and once for 443 |
-| `SITE_FOLDER` | the folder name you used under `/var/www/` |
-| `YOUR_CERTIFICATE` | the folder name under `/etc/letsencrypt/live/` |
-| `SITE_NAME` | the file name you'll use in the commands below — pick anything |
-
-### 2. Install what's missing
-
-Skip anything already installed.
-
-```bash
-sudo apt update
-sudo apt install -y nginx certbot python3-certbot-nginx
-```
-
-With the PHP backend, also:
-
-```bash
-sudo apt install -y php-fpm
-```
-
-### 3. Get an HTTPS certificate
-
-This is what makes your site load over `https://` instead of `http://`.
-Certificates are free and last 90 days; the second command renews them
-automatically.
-
-```bash
-sudo certbot certonly --nginx --cert-name SITE_NAME -d YOUR_DOMAIN
-sudo systemctl enable --now certbot.timer
-```
-
-### 4. Install the site file
-
-```bash
-# Go to the folder where Nginx keeps site files
-cd /etc/nginx/sites-available
-
-# Create the file and paste in the contents of your edited nginx.conf
-sudo nano SITE_NAME
-# Paste, then: CTRL + O, ENTER, CTRL + X
-
-# Switch the site on by copying it into sites-enabled
-sudo cp SITE_NAME ../sites-enabled/
-
-# Check the config for mistakes, then apply it
-sudo nginx -t && sudo systemctl reload nginx
-```
-
-If `nginx -t` reports an error, fix it before reloading — Nginx keeps running on
-the old config until the reload succeeds, so your site stays up.
-
-### If something goes wrong
-
-| What you see | What it usually means |
-|---|---|
-| `cannot load certificate ... Permission denied` | you ran `nginx -t` without `sudo` |
-| `cannot load certificate ... No such file` | wrong certificate name |
-| `no alternative certificate subject name` | the certificate doesn't cover this domain |
-| `unknown directive "http2"` | Nginx older than 1.25 — check with `nginx -v` |
-| NXDOMAIN or a timeout during certbot | your domain's DNS isn't pointing at this server yet |
-| A blank 500 instead of your 404 page | `404.html` is missing from the upload |
-| 502 on `/api`, Node backend | the Node program isn't running |
-| 502 on `/api`, PHP backend | wrong php-fpm socket path in the config |
-
----
-
-## Starting the Node backend on the server
-
-Only for the Node backend. After uploading `out`:
-
-**1. Install its dependencies**
-
-```bash
-cd /var/www/SITE_FOLDER/backend
-npm install
-```
-
-**2. Create its config file**
-
-Make sure `config.js` exists in `out/backend/`. If it doesn't, copy
-`example.config.js` to `config.js` and fill in your values.
-
-**3. Try it out first**
-
-`screen` lets you start a program, walk away, and come back to it later. Use it
-to check the backend actually works before setting it up properly.
-
-```bash
-screen -S node-backend
-# Inside the new screen:
-sudo node /var/www/SITE_FOLDER/backend/_core/index.js
-curl http://127.0.0.1:3000/api/example-public
-```
-
-If `curl` prints a JSON response, the backend is alive. Press `CTRL + A` then `D`
-to leave the screen without stopping the program; `screen -r node-backend` brings
-you back.
-
-**4. Then set it up for real**
-
-`screen` is for testing — the program dies if the server reboots. For a live site
-use **systemd**, the part of Linux that manages background programs. It starts
-your backend at boot and restarts it if it crashes.
-
-Create `/etc/systemd/system/backend-node.service`:
-
-```ini
-[Unit]
-Description=Nibula Node backend
-After=network.target
-
-[Service]
-Type=simple
-User=www-data
-WorkingDirectory=/var/www/SITE_FOLDER/backend
-ExecStart=/usr/bin/node /var/www/SITE_FOLDER/backend/_core/index.js
-Restart=always
-RestartSec=5
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Adjust `WorkingDirectory`, and check the path to `node` with `which node`. Then:
-
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable --now backend-node
-sudo systemctl status backend-node
-```
-
-The last command should say `active (running)`.
-
-(If you already use `pm2`, that works too:
-`pm2 start _core/index.js --name backend-node`.)
-
-### Settings the Node backend reads at startup
-
-These are set in the systemd file, on their own lines, as
-`Environment=KEY=value`. All three have sensible defaults — you usually don't
-need to touch them.
-
-| Setting | Default | What it does |
-|---|---|---|
-| `PORT` | `3000` | the port Node listens on — must match the one in `nginx.conf` |
-| `HOST` | `127.0.0.1` | keep this as-is: it means "local only", so Node is reachable through the web server and not directly from the internet |
-| `DOCUMENT_ROOT` | detected automatically | where `404.html` lives — the folder above `backend/` |
-
-> Error detail is **not** set here. That's the `APP_ENV` key inside `config.js` /
-> `config.php` — see `docs/Backend.md`.