nibula 2.4.3 → 2.4.4

package/docs/Head and SEO.md

@@ -1,198 +0,0 @@
-# Head & SEO
-
-The `<head>` of an HTML page holds the information *about* the page rather than
-its content: the title shown in the browser tab, the description search engines
-display, the image that appears when someone shares the link. Nibula writes all
-of it for you — you just fill in the values.
-
-There are two files to fill in:
-
-- **`src/frontend/data/site.json`** — settings for the whole site
-- **`src/frontend/data/pages.json`** — settings for one page at a time
-
-A page uses its own value when it has one, and falls back to the site-wide value
-when it doesn't. So filling in `site.json` well means most pages need nothing.
-
-## Site-wide settings
-
-Everything in `site.json` is available anywhere in your templates as
-`{{ site.something }}`.
-
-```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",
-  "theme": "dark",
-  "theme_color": "#2a2150",
-  "logo": "/assets/brand/logo.svg",
-  "legal": {
-    "privacy": "",
-    "cookie": "",
-    "terms": "",
-    "copyright": {
-      "year": "2026",
-      "text": "Copyright text"
-    }
-  }
-}
-```
-
-| Field | What it's for |
-|---|---|
-| `site_name` | Your brand or project name |
-| `title` | Default page title — used by any page that doesn't set its own |
-| `description` | Default description — same idea |
-| `keywords` | Default keywords — same idea |
-| `domain` / `url` | Used to build full page addresses for search engines and social previews |
-| `lang` | The language of your site (`en`, `it`, ...) |
-| `author` | Your name |
-| `theme` | Colour scheme of the site: `light` or `dark` |
-| `theme_color` | Colour of the browser bar on phones — should match your theme |
-| `logo` | Path to your logo, also used as the image in social previews |
-| `legal.privacy` / `cookie` / `terms` | Addresses of your legal pages — the footer links to them |
-| `legal.copyright.year` / `text` | The copyright line in the footer |
-
-## Per-page settings
-
-`pages.json` holds one entry per page, and the assistant creates it for you when
-you add a page. Each entry is keyed by the page's `title` from its front matter —
-the camelCase one.
-
-```json
-{
-  "examplePage": {
-    "seo": {
-      "title": "Example Page",
-      "description": "Description",
-      "keywords": "",
-      "noindex": false,
-      "canonical": ""
-    },
-    "cdn": {
-      "css": ["https://example.com/lib.min.css"],
-      "js": ["https://example.com/lib.min.js"]
-    }
-  }
-}
-```
-
-| Field | What it's for | If you leave it empty |
-|---|---|---|
-| `seo.title` | The page's title, shown in the browser tab and in search results | Uses the site-wide `title` |
-| `seo.description` | The short summary search engines show under the title | Uses the site-wide `description` |
-| `seo.keywords` | Keywords for this page | Uses the site-wide `keywords` |
-| `seo.noindex` | Set to `true` to ask search engines **not** to list this page | The page can be found normally |
-| `seo.canonical` | The one official address of this page, if the same content is reachable at more than one URL | Worked out automatically |
-| `cdn.css` / `cdn.js` | Extra stylesheets or scripts loaded from the internet, on this page only | Nothing extra is loaded |
-
-> ⚠️ The assistant fills new entries with placeholder text like `"Description"`.
-> Replace it — a page left that way tells search engines and AI crawlers that its
-> description is literally "Description".
-
-### How the fallback works
-
-Site-wide values are defaults, not duplicates. You don't need to repeat them per
-page. This is what the template actually does:
-
-```njk
-{{ pageData.seo.title or title or site.title }}
-{{ pageData.seo.description or site.description }}
-{{ pageData.seo.keywords or site.keywords }}
-```
-
-Read it as: use the page's value; if there isn't one, use the site's.
-
-`noindex` and `canonical` work per-page only — there's no site-wide version,
-because "hide the whole site from search" and "one address for the whole site"
-aren't things you'd want.
-
-## Theme
-
-One value in `site.json` controls the colour scheme everywhere:
-
-```html
-<html data-theme="{{ site.theme }}" data-bs-theme="{{ site.theme }}">
-<meta name="color-scheme" content="{{ site.theme }}">
-<meta name="theme-color" content="{{ site.theme_color }}">
-```
-
-| What it sets | Why it's there |
-|---|---|
-| `data-theme` | Your own hook — target it in your SCSS to define theme colours |
-| `data-bs-theme` | Bootstrap's dark mode switch. Harmlessly ignored with other frameworks |
-| `color-scheme` | Standard CSS — makes scrollbars, form fields and autofill match your theme |
-| `theme-color` | The colour of the browser bar on phones |
-
-Keep `theme` and `theme_color` in agreement: a dark theme with a white
-`theme_color` gives a white browser bar sitting on top of a dark page.
-
-See the **Styling with SCSS** DOC file for how to hook your own colours to
-`data-theme`.
-
-## Favicon
-
-The favicon is the small icon in the browser tab. The three tags are written
-directly in `base.njk`. To change the icons, replace the files in
-`src/frontend/assets/brand/` **keeping the same names**:
-
-```html
-<link rel="icon" type="image/svg+xml" href="{{ '/assets/brand/favicon.svg' | url }}">
-<link rel="icon" type="image/png" sizes="32x32" href="{{ '/assets/brand/favicon-32.png' | url }}">
-<link rel="apple-touch-icon" sizes="180x180" href="{{ '/assets/brand/apple-touch-icon.png' | url }}">
-```
-
-| File | What uses it |
-|---|---|
-| `favicon.svg` | Modern browsers — scales to any size |
-| `favicon-32.png` | Older browsers and some crawlers |
-| `apple-touch-icon.png` | The icon iOS uses when someone saves your site to their home screen. Must be 180×180 and **not** transparent — iOS turns transparency into black |
-
-> ⚠️ Without `apple-touch-icon.png`, iOS uses a screenshot of your page as the
-> home screen icon instead.
-
-## Where all this is written
-
-Everything above is produced by `src/frontend/layouts/base.njk`, which looks up
-the current page's entry like this:
-
-```njk
-{% set pageKey = title %}
-{% set pageData = pages[pageKey] %}
-```
-
-You only need to edit `base.njk` for something the boilerplate doesn't cover — a
-web font, an analytics snippet. For everything documented here, change the values
-in `site.json` and `pages.json` instead.
-
-> ⚠️ Paths in `base.njk` go through `| url`. That filter makes them work when the
-> site is published in a subfolder rather than at the root of a domain — GitHub
-> Pages being the common case. Remove it and every stylesheet and script breaks
-> there.
-
-## Files for search engines and AI
-
-Three files are generated automatically and published with your site:
-
-| File | What it's for | Reachable at |
-|---|---|---|
-| `llms.txt` | Describes your site and lists its pages, for AI models | `yoursite.com/llms.txt` |
-| `robots.txt` | Tells search engines what they may and may not crawl | `yoursite.com/robots.txt` |
-| `sitemap.xml` | Lists your pages so search engines find them all | `yoursite.com/sitemap.xml` |
-
-They are built from templates in `src/frontend/indexing/`. `llms.txt` and
-`sitemap.xml` build their page lists the same way: they go through every page and
-leave out drafts, the 404 page, and anything marked `noindex`. Creating a page
-with the assistant is enough for it to appear in both — there is no list to keep
-up to date by hand.
-
-To change the wording or the fixed parts, edit
-`src/frontend/indexing/llms.njk` or `src/frontend/indexing/robots.njk`.
-
-> These three files must stay publicly reachable. If you block them in your server
-> config, search engines and AI models can't read them.

package/docs/JavaScript.md

@@ -1,127 +0,0 @@
-# JavaScript
-
-> 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/`.
-
-## Page JS
-
-Each page has its own JS entry point in `src/frontend/js/pages/`, bundled and minified by esbuild and loaded automatically by `base.njk`.
-
-Import only what the page needs.
-
-### examplePage.js <small>(`src/frontend/js/pages/`)</small>
-
-```js
-import '../global.js';
-
-// import { initExampleModule } from '../modules/exampleModule.js';
-
-document.addEventListener("DOMContentLoaded", () => {
-    // initExampleModule();
-});
-
-// Page logic here
-```
-
-## Global JS
-
-Some code has to run on every page: a header menu, a theme toggle, a cookie banner. Repeating it in every page entry point means you'll eventually forget it on one of them, and the bug only shows up on that single page.
-
-That's what `global.js` is for. It lives in `src/frontend/js/`, every page entry point imports it, and it takes care of running the shared modules.
-
-### global.js <small>(`src/frontend/js/`)</small>
-
-```js
-// import { initExampleModule } from './modules/exampleModule.js';
-
-function initGlobal() {
-    // initExampleModule();
-}
-
-// Global logic here
-
-// Do not touch
-// This instruction starts global.js itself
-document.addEventListener('DOMContentLoaded', initGlobal);
-```
-
-Pages import it without curly braces, since there is nothing to export — the module runs on its own as soon as it's part of the bundle:
-
-```js
-import '../global.js';
-```
-
-Note the difference in import paths. A page entry point sits inside `js/pages/`, so it reaches a module with `'../modules/exampleModule.js'`. `global.js` sits directly in `js/`, one level up, so the same module is `'./modules/exampleModule.js'`.
-
-### A concrete example: the header menu
-
-A responsive header has a burger button that opens the navigation on small screens. The header is included in `base.njk`, so it's on every page — a textbook case for `global.js`.
-
-Write the behaviour as a normal module:
-
-### header.js <small>(`src/frontend/js/modules/`)</small>
-```js
-export function initHeader() {
-    const toggle = document.querySelector('.menu-toggle');
-    const menu = document.querySelector('.menu');
-
-    if (!toggle || !menu) return;
-
-    toggle.addEventListener('click', () => {
-        menu.classList.toggle('is-open');
-    });
-}
-```
-
-Then wire it up once, in `global.js`:
-
-```js
-import { initHeader } from './modules/header.js';
-
-function initGlobal() {
-    initHeader();
-}
-
-// Do not touch
-// This instruction starts global.js itself
-document.addEventListener('DOMContentLoaded', initGlobal);
-```
-
-The burger now works on every page, and no page entry point had to change. Adding another global behaviour later is two lines: one import, one call inside `initGlobal()`.
-
-The early `return` matters: if a page has no header, the module does nothing instead of throwing an error that would stop your other scripts.
-
-### Global or page module?
-
-Use `global.js` for behaviour tied to something present on every page — anything included in `base.njk`, essentially.
-
-Keep it in the page entry point when only one or two pages need it. Everything imported by `global.js` ends up in *every* page bundle, so a heavy module used by a single page belongs in that page instead.
-
-## Modules
-
-Modules live in `src/frontend/js/modules/`. Modules that interact with the DOM must be called inside `DOMContentLoaded`; others can be called anywhere.
-
-## Adding a module
-
-Create a new `.js` file in `src/frontend/js/modules/`. Subfolders are allowed.
-
-Use ESM syntax — esbuild handles the bundling:
-
-### exampleModule.js <small>(`src/frontend/js/modules/`)</small>
-
-```js
-export function exampleModule() {
-    // Module logic here
-}
-```
-
-Then import it in the pages that need it:
-
-```js
-import { exampleModule } from '../modules/exampleModule.js';
-```
-
-In TypeScript, omit the extension:
-
-```ts
-import { exampleModule } from '../modules/exampleModule';
-```

package/docs/Project structure.md

@@ -1,66 +0,0 @@
-# Project Structure
-
-> 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/`.
-
-Nibula ships a fixed layout so you always know where to put your hands. Inside these folders you're free to organize as you like — subfolders in `components/`, `modules/` and `api/` are all fair game.
-
-## The tree
-
-```
-your-project/
-├── .eleventy.js          # Eleventy configuration
-├── nginx.conf            # nginx site file
-├── package.json
-├── out/                  # Build output — never edit, never commit
-└── src/
-    ├── backend/          # REST API — see docs/Backend.md
-    └── frontend/
-        ├── assets/       # Images, fonts, brand files
-        │   └── brand/    # Favicons, logo etc
-        ├── components/   # Reusable .njk fragments and .md content
-        │   └── global/   # Header and footer, included in every page
-        ├── data/         # site.json and pages.json
-        ├── hosting/      # .htaccess and web.config
-        ├── indexing/     # llms, robots and sitemap templates
-        ├── js/           # global.js, modules/, pages/
-        ├── layouts/      # base.njk — the HTML skeleton every page extends
-        ├── routes/       # One file per page
-        └── scss/         # _root.scss, _global.scss, modules/, pages/
-```
-
-## Where things happen
-
-| I want to... | Go to |
-|---|---|
-| Add a page | `nib cli` → creates the files in `routes/`, `scss/pages/`, `js/pages/` |
-| Write the content of a page | `routes/` |
-| Build a reusable block of markup | `components/` |
-| Write long prose in Markdown | `components/` — see docs/Components.md |
-| Change the header or footer | `components/global/` |
-| Style one page | `scss/pages/` |
-| Style every page | `scss/_global.scss` |
-| Define a variable used across the site | `scss/_root.scss` |
-| Run a script on one page | `js/pages/` |
-| Run a script everywhere | `js/global.js` |
-| Change the site name, URL, author | `data/site.json` |
-| Change a page's SEO | `data/pages.json` |
-| Edit the HTML `<head>` | `layouts/base.njk` |
-| Give one page a different skeleton | `layouts/` — add your own, see docs/Components.md |
-| Add an API endpoint | `backend/api/` |
-
-## Two folders worth a note
-
-**`out/`** is generated by every build. Editing anything in it means losing the change the next time you run `nib run` or `nib build`. Always edit the source in `src/` — including `.htaccess` and `web.config`, whose sources live in `src/frontend/hosting/`.
-
-**`data/`** feeds the build but is never published: it holds the full page map, including pages you marked `noindex`, so it stays out of the output on purpose.
-
-## What you can rearrange
-
-Subfolders are allowed wherever content is yours to organize:
-
-- `components/` — nest as deep as you like; includes take the path relative to `components/`, and so does the `markdownPath` filter
-- `scss/modules/` and `js/modules/` — same idea, remember to update the relative import paths
-- `layouts/` — extra layouts alongside `base.njk`; routes pick one by filename
-- `backend/api/public/` and `protected/` — subfolders become part of the URL
-
-The folders in the tree above are the part to leave alone: paths are wired into `.eleventy.js`, the build scripts and the assistant, so renaming one breaks the build.

package/docs/Styling with SCSS.md

@@ -1,147 +0,0 @@
-# Styling with SCSS
-
-## Page CSS
-
-Each page has its own SCSS entry point in `src/frontend/scss/pages/`
-
-It must contain `_root.scss` + any other module that you need and its own specific css rules
-
-`_root.scss` uses `@use` to enable namespaced access (`root.$var`); other modules use `@import` as they don't expose variables.
-
-### examplePage.scss <small>(`src/frontend/scss/pages/`)</small>
-```scss
-//==========================
-// CSS MODULES IMPORTS
-//==========================
-
-@use "../root" as root;
-
-@import "../global";
-
-//==========================
-// PAGE CUSTOM CSS RULES
-//==========================
-
-body {
-  background-color: root.$primary;
-}
-```
-
-## Global Variables
-
-Instead of using `:root` in your custom modules or pages, the best thing to do is to centralize all your variables in a single file (that will be tree-shaken automatically by Sass)
-
-### _root.scss <small>(`src/frontend/scss/`)</small>
-```scss
-$header-height: 10vh;
-
-// Usage example (in any other file): 
-header {
-  height: root.$header-height;
-}
-```
-
-## Scss modules
-
-You can create your custom css modules by creating a new `.scss` file in `src/frontend/scss/modules/` (the name of the file must start with `_`)
-
-You can create subfolders if you want to refactor the structure, but be sure to update the relative paths in the pages that import them
-
-### _yourModule.scss <small>(`src/frontend/scss/modules/subfolder/`)</small>
-```scss
-@use '../../root' as root;
-
-@import '../../global';
-
-body {
-  background-color: root.$primary;
-}
-```
-
-### examplePage.scss
-```scss
-@import "../modules/subfolder/yourModule";
-
-// This page will now inherit the body tag rules
-// If the same property is declared in both, the last imported one wins
-body {
-  color: root.$dark;
-}
-```
-
-### Pre-existing modules
-
-| File | Purpose |
-|---|---|
-| `_typography.scss` | Font rules |
-| `_header.scss` | Header styles |
-| `_footer.scss` | Footer styles |
-| `_mobile.scss` | Media query rules |
-| `_animations.scss` | Keyframe animations (`fade-in`, `spin`) |
-| `_markdown.scss` | Styling for Markdown rendered with `renderFile`. See **Components** DOC file |
-
-> If you don't use Markdown files as components, comment its import from `_global.scss`.
-
-## CSS Framework
-
-Some of the most popular css frameworks that supports scss with modules are already installed in `node_modules`
-
-You can choose one or none of them (more than 1 works, but you may get in various conflicts)
-
-To enable/disable them you have to modify 3 files around the project by just commenting them
-
-### 1. _global.scss <small>(`src/frontend/scss/`)</small>
-```scss
-@import "modules/frameworks/bootstrap";
-// @import "modules/frameworks/bulma";
-// @import "modules/frameworks/foundation";
-// @import "modules/frameworks/uikit";
-```
-
-### 2. base.njk <small>(`src/frontend/layouts/`)</small>
-
-```html
-{# Bootstrap JS #}
-<script src="{{ '/js/bootstrap.bundle.min.js' | url }}" defer></script>
-
-{# Foundation JS #}
-{# <script src="{{ '/js/foundation.min.js' | url }}" defer></script> #}
-
-{# UIkit JS #}
-{# <script src="{{ '/js/uikit.min.js' | url }}" defer></script> #}
-{# <script src="{{ '/js/uikit-icons.min.js' | url }}" defer></script> #}
-
-{# Bulma — no JS needed #}
-```
-
-### 3. .eleventy.js <small>(project root)</small>
-
-```javascript
-eleventyConfig.addPassthroughCopy({
-  // Bootstrap
-  "node_modules/bootstrap/dist/js/bootstrap.bundle.min.js": "js/bootstrap.bundle.min.js",
-  "node_modules/bootstrap-icons/font/fonts": "css/fonts",
-
-  // Foundation
-  // "node_modules/foundation-sites/dist/js/foundation.min.js": "js/foundation.min.js",
-
-  // UIkit
-  // "node_modules/uikit/dist/js/uikit.min.js": "js/uikit.min.js",
-  // "node_modules/uikit/dist/js/uikit-icons.min.js": "js/uikit-icons.min.js",
-
-  // Bulma — CSS only, no JS passthrough needed
-});
-```
-
-> ⚠️ Changes to `.eleventy.js` are not picked up while the dev server is running — restart it.
-
-> These three files are set up for you when you pick a framework during `nib new`. You only need to edit them by hand if you change your mind later.
-
-### Reducing bundle size
-
-To reduce the bundle size, open the corresponding framework file (`src/frontend/scss/modules/frameworks/`) and comment out any modules you don't need
-
-```scss
-@import "bootstrap/scss/card"; // Cards
-@import "bootstrap/scss/carousel"; // Carousel
-```