nibula 1.6.2 → 2.0.1

package/.eleventy.js

@@ -27,8 +27,11 @@ module.exports = function (eleventyConfig) {
     copyRecursiveSync("src/backend", `${OUTPUT_DIR}/backend`);
   });
 
-  eleventyConfig.addPassthroughCopy("src/frontend/.htaccess");
-  eleventyConfig.addPassthroughCopy("src/frontend/web.config");
+  eleventyConfig.addPassthroughCopy({
+    "src/frontend/hosting/.htaccess": ".htaccess",
+    "src/frontend/hosting/web.config": "web.config",
+  });
+  
   eleventyConfig.addPassthroughCopy("src/frontend/assets");
   eleventyConfig.addPassthroughCopy("src/frontend/robots.txt");
 

package/CHANGELOG.md

@@ -5,13 +5,120 @@ All notable changes to Nibula are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.6.2] - 2026-08-07
+## [2.0.1] - 2026-08-08
 
 ### Added
-- `nib --version` (also `-v`, `v`, `version`) prints the version number on its own line. Inside a project it reports the project's own copy, which is the one actually running the command.
+- `docs/Components.md` documents custom layouts. `base.njk` was presented as the
+  only layout there is, so a page that doesn't fit the standard shell — a landing
+  page with no header or footer, a full-screen login — had no documented way out.
+  Copying `base.njk` and pointing a route at the copy was already supported;
+  nothing said so.
+- `docs/Head and SEO.md` shows where the tags are actually written, including the
+  `pageKey` lookup that ties a route's `title` to its record in `pages.json`, and
+  warns against removing the `url` filter from asset paths — it is what keeps a
+  site published under a subpath from 404ing every stylesheet and script.
+- `docs/Creating pages.md` covers the `layout` front matter field, which the file
+  showed in every example without ever explaining.
 
 ### Fixed
-[...le quattro voci di prima, invariate...]
+- `src/frontend/ts/global.ts` imported `exampleModule` for real while leaving the
+  call commented out, so a new TypeScript project started with an unused import
+  and a stale path in the comment above it. It now matches `global.js`, where the
+  import is commented too.
+- The `site.json` snippet in `docs/Components.md` was not valid JSON: the opening
+  and two closing braces were missing and three `//` comments sat inside it, so
+  copying it into the file broke the build.
+- `docs/Head and SEO.md` listed `favicon-48.png` among the favicon files. No tag
+  in `base.njk` loads it.
+
+### Changed
+- `docs/Creating pages.md` no longer re-explains component includes and the
+  `pages.json` stub, which are documented in full elsewhere and had started to
+  drift.
+- Nunjucks snippets in `docs/Components.md` are tagged as such instead of as
+  JavaScript.
+- `docs/Project structure.md` points at `layouts/` for pages that need their own
+  skeleton.
+  
+## [2.0.0] - 2026-08-07
+
+### Breaking
+
+Existing projects keep running the Nibula version they were built with. These
+steps apply only when you run `npm install nibula@latest` inside a project. Do
+them in one pass, before the next build.
+
+- **`page-components.njk` no longer exists.** Its `elif` chain is replaced by
+  includes written directly in each route. For every page, move the includes
+  from its `elif` block into the matching file in `src/frontend/routes/`, then
+  delete `src/frontend/layouts/page-components.njk`.
+- **Every route's layout becomes `base.njk`.** Change `layout: page-components.njk`
+  to `layout: base.njk` in the front matter of each file in `routes/`.
+- **`index.njk` and `404.njk` move into `routes/`.** They sat at the root of
+  `src/frontend/`; every page now lives in one place.
+- **`llms.njk`, `robots.njk` and `sitemap.njk` move into `src/frontend/indexing/`.**
+  Their `permalink` values are unchanged, so the published URLs stay the same.
+- **`.htaccess` and `web.config` move into `src/frontend/hosting/`.** The build
+  still places them in the root of the output folder, so what you deploy is
+  unchanged. `nginx.conf` stays at the project root: it is installed on the
+  server by hand, not published with the site.
+
+### Added
+
+- `docs/Project structure.md` maps the whole project and lists where to go for
+  each kind of change. There was no overview of the layout anywhere, so the two
+  new folders — and the older ones — had to be inferred from the file tree.
+- `src/frontend/components/not-found.njk` holds the 404 page markup, included by
+  `routes/404.njk`.
+
+### Changed
+
+- **`llms.txt` is generated from page data instead of being hardcoded.** It
+  listed the homepage and nothing else, so every other page was invisible to AI
+  crawlers unless you edited the template by hand. It now walks the same
+  collection `sitemap.njk` does, reading each page's title and description from
+  `pages.json` and skipping drafts, the 404 page and anything marked `noindex`.
+  Creating a page with the assistant is enough to have it listed.
+- **Components are included in the route that renders them.** Composition lived
+  in a single shared layout, so adding a page meant appending a branch to a file
+  that grew with every page, and reading one page's structure meant scrolling
+  past all the others. A route now includes what it needs, and what a page
+  contains is visible in the page itself.
+- **The assistant no longer edits Nunjucks templates.** Creating, renaming and
+  removing a page used to rewrite `page-components.njk` with regular expressions
+  against the template's syntax. That step is gone; the assistant now touches
+  only files it fully controls.
+- **Documentation catches up with the code.** `Head & SEO` opened by pointing at
+  `pages.json` and `{{ pages.* }}` for the global settings, which have lived in
+  `site.json` since 1.6.0, and still listed `legal.cookieControls`, removed in
+  the same release. `JavaScript` claimed `global.js` sits in the modules folder,
+  which stopped being true when it moved up a level — the surrounding example
+  already contradicted it. `Styling with SCSS` referred to the Eleventy config
+  as `eleventy.config.js`.
+- New pages are scaffolded with a commented example include instead of a warning
+  not to edit the file.
+
+### Removed
+
+- `src/frontend/layouts/page-components.njk`, and with it the `pageComponents`
+  configuration block, its six log messages, and its entry in the project's
+  required-files check.
+- The include of `404/_404.njk`, a component that was never shipped. It survived
+  only because of `ignore missing`, which silently swallowed it on every build.
+
+### Notes
+
+- `routes/` is no longer created on demand or removed when empty: with
+  `index.njk` and `404.njk` inside, it always exists. The same on-demand handling
+  still applies to `scss/pages/` and `js/pages/`.
+- Writing markup directly in a route works and is fine for a simple page.
+  Components remain the recommendation when there is something to reuse, not a
+  requirement.
+
+## [1.6.2] - 2026-08-07
+
+### Added
+- `nib --version` (also `-v`, `v`, `ver`, `version`) prints the version number on its own line. Inside a project it reports the project's own copy, which is the one actually running the command.
 
 ### Changed
 - `docs/Styling with SCSS.md` now matches the template: the Nunjucks snippets include the `url` filter and the config file is named `.eleventy.js`.

package/bin/nibula.js

@@ -293,6 +293,14 @@ async function main() {
             usage(pkg.version);
             break;
         }
+        case 'version':
+        case 'v':
+        case 'ver':
+        case '-v':
+        case '--version': {
+            console.log(pkg.version);
+            break;
+        }
         default:
             console.error(`${color.red}\nUnknown command:${color.reset} ${cmd}`);
             usage(pkg.version);

package/docs/Assistant CLI.md

@@ -33,7 +33,7 @@ For a page named `my-page`, the following files are created:
 | `src/frontend/js/pages/myPage.js` | JS entry point |
 | `src/frontend/routes/my-page.njk` | Nunjucks template |
 
-It also adds an `elif` block in `page-components.njk` and a stub entry in `pages.json`:
+It also adds a stub entry in `pages.json`:
 
 ```json
     "myPage": {
@@ -51,13 +51,17 @@ It also adds an `elif` block in `page-components.njk` and a stub entry in `pages
     }
 ```
 
+The route is created with an empty body and a commented example — you decide which components go in it. See **Components** DOC file.
+
 ## Remove page
 
-Deletes all source files for the page and cleans up the output directory, `page-components.njk`, and `pages.json`.
+Deletes all source files for the page, cleans up the output directory, and removes the record from `pages.json`.
 
 ## Rename page
 
-Renames all three source files, updates the `elif` block in `page-components.njk`, and renames the record in `pages.json`. Nothing inside the record is touched — your SEO title, description and CDN links stay exactly as you wrote them.
+Renames all three source files, updates the `permalink` in the route's front matter, and renames the record in `pages.json`. Nothing inside the record is touched — your SEO title, description and CDN links stay exactly as you wrote them.
+
+The includes you wrote inside the route move with the file, since the route itself is renamed rather than rewritten.
 
 ## Configure output path
 

package/docs/Backend.md

@@ -42,6 +42,23 @@ src/backend/
 > the matching `example.config.*`, and are git-ignored so your secrets stay
 > local. If `config.*` is missing (e.g. after a fresh clone), copy the example.
 
+### Installing Composer packages (PHP)
+
+Backend dependencies live in `src/backend/_core`, next to `composer.json`.
+Install from there, not from the project root:
+
+```bash
+cd src/backend/_core
+composer require vendor/package
+```
+
+`_core/init.php` already requires Composer's autoloader, so an installed package
+is usable in your endpoints straight away — there is no extra `require` to add.
+
+Packages land in `src/backend/_core/vendor/`, which is git-ignored. After a fresh
+clone that folder is missing and the backend won't start at all: run
+`composer install` from `src/backend/_core` to restore it.
+
 ## How routing works
 
 The file path inside `api/` maps directly to the URL. The `public` / `protected`

package/docs/Components.md

@@ -11,44 +11,45 @@ Create a new `.njk` file anywhere inside `src/frontend/components/`. You can org
 ```
 src/frontend/components/
 ├── global/
-├── layouts/
+│   ├── header.njk
+│   └── footer.njk
 ├── modals/
-│   └── privacyModal.njk # You can move it to a modals/subfolder
+│   └── privacyModal.njk
+├── not-found.njk
 ├── welcome.njk
 ```
 
 ## Include a component
 
-To render a component inside a page, navigate to `src/frontend/layouts/` and edit `page-components.njk`
+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
 
-### page-components.njk <small>(`src/frontend/layouts/`)</small>
+### example-page.njk <small>(`src/frontend/routes/`)</small>
 
-```js
-{% if title == "homepage" %}
-{% include "welcome.njk" %}
+```njk
+---
+title: "examplePage"
+permalink: "/example-page/"
+layout: base.njk
+---
 
-{% elif title == "examplePage" %}
 {% include "example-component-1.njk" %}
 {% include "subfolder/example-component-2.njk" %}
-
-{% else %}
-{% include "404/_404.njk" %}
-{{ content | safe }}
-{% endif %}
 ```
 
-Add a new `{% elif %}` block for each page, listing its components in order. If a component lives in a subfolder, specify the relative path accordingly
+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"`
 
-> ⚠️ A new `elif` block is automatically added when you create a page via the Assistant CLI
+> ⚠️ If you move or delete a component, update every route that includes it or the build will fail
 
-> ⚠️ If you move or delete a component, always update `page-components.njk` or the site will break
+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
-```js
+```njk
 <section class="hero">
   {% include "hero/hero-title.njk" %}
   {% include "hero/hero-button.njk" %}
@@ -61,33 +62,87 @@ A component can include other components. This is useful for breaking complex se
 
 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:
+
+```njk
+<body>
+    <main>
+        {{ content | safe }}
+    </main>
+</body>
+```
+
+Then point the route at it:
+
+### landing.njk <small>(`src/frontend/routes/`)</small>
+
+```njk
+---
+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": "", // This is supposed to contain a link
-  "cookie": "", // This is supposed to contain a link
-  "terms": "", // This is supposed to contain a link
-  "copyright": {
-    "year": "2026",
-    "text": "All rights reserved."
+{
+  "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
-```js
+```njk
 <p>{{ site.title }}</p>
 <a href="{{ site.legal.privacy }}">Privacy Policy</a>
 <img src="{{ site.logo }}" alt="{{ site.title }}">
@@ -107,7 +162,7 @@ Create `test.json`, put anything you want inside it, and every key is reachable
 ```
 
 ### Usage in any `.njk` file
-```js
+```njk
 <p>{{ test.testMessage }}</p>
 ```
 
@@ -130,7 +185,7 @@ Values can be anything JSON allows, so a list lets you loop instead of copying m
 }
 ```
 
-```js
+```njk
 {% for link in test.links %}
   <a href="{{ link.url }}">{{ link.label }}</a>
 {% endfor %}

package/docs/Creating pages.md

@@ -13,21 +13,21 @@ For a page named `my-page`:
 | `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
 
-1. Create a component in `src/frontend/components/` (e.g. `my-component.njk`)
-2. Include it in `src/frontend/layouts/page-components.njk` inside the generated `elif` block:
+The route is created empty. Write your HTML in its body, or include components — see the **Components** DOC file.
 
-```njk
-{% elif title == "myPage" %}
-  {% include "my-component.njk" ignore missing %}
-```
+## URL and title
 
-See **Components** DOC file for more info
+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.
 
-## URL and title
+## 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.
 
-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 — do not change it.
+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)
 
@@ -36,8 +36,8 @@ To create a URL like `domain.it/about/team`, edit the `permalink` in `src/fronte
 ```njk
 ---
 title: "team"
-permalink: "about/team/"
-layout: page-components.njk
+permalink: "/about/team/"
+layout: base.njk
 ---
 ```
 
@@ -47,24 +47,4 @@ The parent path (`about`) does **not** need to exist as a real page — it's jus
 |---|---|---|
 | `/team/` | `/team/` | `routes/team.njk` |
 | `/about/team/` | `/about/team/` | `routes/team.njk` |
-| `/company/about/team/` | `/company/about/team/` | `routes/team.njk` |
-
-## SEO
-
-The CLI creates a stub entry in `src/frontend/data/pages.json`. Fill it in:
-
-```json
-    "myPage": {
-      "seo": {
-        "title": "My Page",
-        "description": "Description",
-        "keywords": "",
-        "noindex": false,
-        "canonical": ""
-      },
-      "cdn": {
-        "css": [],
-        "js": []
-      }
-    }
-```
+| `/company/about/team/` | `/company/about/team/` | `routes/team.njk` |

package/docs/Deploy.md

@@ -39,6 +39,16 @@ dependencies.
 **Node backend:** Node.js 18+ and shell access to run a persistent process — a
 VPS you control.
 
+## Editing the server config
+
+`.htaccess` and `web.config` are in the root of `out`, ready to upload. To change
+a rule, edit the source in `src/frontend/hosting/` — a change made directly in
+`out` is lost on the next build.
+
+`nginx.conf` works differently: it sits in the project root and is **not** part
+of `out`, because nginx reads no per-directory config. You install it on the
+server by hand, as described below.
+
 ---
 
 ## Shared hosting (Apache)

package/docs/Head and SEO.md

@@ -1,6 +1,6 @@
 # Head & SEO
 
-Global settings live in `src/frontend/data/pages.json` and are available everywhere via `{{ pages.* }}`.
+Global settings live in `src/frontend/data/site.json` and are available everywhere via `{{ site.* }}`.
 
 ## Global fields
 
@@ -15,11 +15,11 @@ Global settings live in `src/frontend/data/pages.json` and are available everywh
   "lang": "en",
   "author": "Name and surname",
   "theme": "dark",
+  "theme_color": "#2a2150",
   "logo": "/assets/brand/logo.svg",
   "legal": {
     "privacy": "",
     "cookie": "",
-    "cookieControls": "",
     "terms": "",
     "copyright": {
       "year": "2026",
@@ -41,7 +41,7 @@ Global settings live in `src/frontend/data/pages.json` and are available everywh
 | `theme` | Site color scheme (`light` / `dark`) — sets `data-theme`, `data-bs-theme` and `color-scheme` |
 | `theme_color` | Browser UI / PWA bar color — should match the chosen `theme` |
 | `logo` | Path to the logo, also used as social image |
-| `legal.privacy` / `cookie` / `cookieControls` / `terms` | Legal page URLs |
+| `legal.privacy` / `cookie` / `terms` | Legal page URLs |
 | `legal.copyright.year` / `text` | Footer copyright |
 
 ## Per-page SEO and CDN
@@ -68,13 +68,15 @@ Per-page settings live in `src/frontend/data/pages.json`, available via `{{ page
 
 | Field | Purpose | If empty / absent |
 |---|---|---|
-| `seo.title` | Page title | Falls back to global `title` |
-| `seo.description` | Meta description | Falls back to global `description` |
+| `seo.title` | Page title, and the page's label in `llms.txt` | Falls back to global `title` |
+| `seo.description` | Meta description, and the page's summary in `llms.txt` | Falls back to global `description` |
 | `seo.keywords` | Meta keywords | Falls back to global `keywords` |
-| `seo.noindex` | If `true`, emits `<meta name="robots" content="noindex, follow">` and drops the page from the sitemap | Page is indexable |
+| `seo.noindex` | If `true`, emits `<meta name="robots" content="noindex, follow">` and drops the page from both the sitemap and `llms.txt` | Page is indexable |
 | `seo.canonical` | Absolute canonical URL override | Computed as `url + page.url` |
 | `cdn.css` / `cdn.js` | Extra per-page CDN links | No extra links loaded |
 
+The assistant creates the stub entry when you add a page; a page left with the placeholder description will advertise itself that way to AI crawlers.
+
 ## Fallback logic
 
 Global values are defaults, not duplicates. A page value is used when present; otherwise the global one applies:
@@ -121,20 +123,34 @@ The three favicon tags are hardcoded in `base.njk`. To change the icons, replace
 | File | Purpose |
 |---|---|
 | `favicon.svg` | Modern browsers, scales to any size |
-| `favicon-48.png` | Fallback for older browsers and some crawlers |
 | `favicon-32.png` | Fallback for older browsers and some crawlers |
 | `apple-touch-icon.png` | iOS home screen icon — 180×180, must be opaque (iOS renders transparency as black) |
 
 > ⚠️ Without `apple-touch-icon.png`, iOS uses a screenshot of the page as the home screen icon.
 
+## Where the tags are written
+
+All of the above is rendered by `src/frontend/layouts/base.njk`, which reads the page's record with:
+
+```njk
+{% set pageKey = title %}
+{% set pageData = pages[pageKey] %}
+```
+
+Edit the template when you need a tag the boilerplate doesn't cover — a font `<link>`, an analytics snippet. For everything listed here, change the values in `site.json` and `pages.json` instead.
+
+> ⚠️ Asset paths in `base.njk` go through the `url` filter. It makes them work when the site is published under a subpath — GitHub Pages being the usual case. Removing it 404s every stylesheet and script there.
+
 ## AI & SEO bots
 
-`llms.txt`, `robots.txt` and `sitemap.xml` are generated from `.njk` templates and are publicly reachable (they must not be blocked by the server config).
+`llms.txt`, `robots.txt` and `sitemap.xml` are generated from `.njk` templates in `src/frontend/indexing/` and are publicly reachable (they must not be blocked by the server config).
 
 | File | Purpose | Reachable at |
 |---|---|---|
-| `llms.njk` | Tells AI models what the site is about | `yoursite.com/llms.txt` |
+| `llms.njk` | Describes the site and lists its pages for AI models | `yoursite.com/llms.txt` |
 | `robots.njk` | Controls search-engine crawling | `yoursite.com/robots.txt` |
-| `sitemap.njk` | Lists indexable pages (skips drafts, 404, and `noindex`) | `yoursite.com/sitemap.xml` |
+| `sitemap.njk` | Lists indexable pages | `yoursite.com/sitemap.xml` |
+
+`llms.njk` and `sitemap.njk` build their lists the same way: they walk every page, then skip drafts, the 404 page, and anything with `seo.noindex` set to `true`. Creating a page with the assistant is enough to have it appear in both — there is no separate list to maintain.
 
-To customize, edit `src/frontend/llms.njk` or `src/frontend/robots.njk` directly.
+To customize the wording or the fixed sections, edit `src/frontend/indexing/llms.njk` or `src/frontend/indexing/robots.njk` directly.

package/docs/{Javascript.md → JavaScript.md}

@@ -31,7 +31,7 @@ That's what `global.js` is for. It lives in `src/frontend/js/`, every page entry
 ### global.js <small>(`src/frontend/js/`)</small>
 
 ```js
-// import { initExampleModule } from './exampleModule.js';
+// import { initExampleModule } from './modules/exampleModule.js';
 
 function initGlobal() {
     // initExampleModule();
@@ -50,7 +50,7 @@ Pages import it without curly braces, since there is nothing to export — the m
 import '../global.js';
 ```
 
-Note that the import path inside `global.js` is `'./exampleModule.js'` and not `'../modules/exampleModule.js'`: `global.js` already sits in the modules folder, next to the modules it imports.
+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
 

package/docs/Project structure.md

@@ -0,0 +1,65 @@
+# 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
+        │   └── 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/` |
+| 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/`
+- `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

@@ -111,7 +111,7 @@ To enable/disable them you have to modify 3 files around the project by just com
 {# Bulma — no JS needed #}
 ```
 
-### 3. eleventy.js
+### 3. .eleventy.js <small>(project root)</small>
 
 ```javascript
 eleventyConfig.addPassthroughCopy({
@@ -130,7 +130,9 @@ eleventyConfig.addPassthroughCopy({
 });
 ```
 
-> ⚠️ Changes to `eleventy.js` are not picked up while the dev server is running — restart it.
+> ⚠️ 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
 

package/nginx.conf

@@ -29,7 +29,7 @@ server {
 
 # HTTPS (443) configuration
 server {
-### Essentials
+
     listen      443 ssl;
     listen      [::]:443 ssl;
 
@@ -40,13 +40,13 @@ server {
     root        /var/www/SITE_FOLDER;
     index       index.html;
 
-### Certificate
+    # Certificate
     ssl_certificate     /etc/letsencrypt/live/YOUR_CERTIFICATE/fullchain.pem;
     ssl_certificate_key /etc/letsencrypt/live/YOUR_CERTIFICATE/privkey.pem;
     include             /etc/letsencrypt/options-ssl-nginx.conf;
     ssl_dhparam         /etc/letsencrypt/ssl-dhparams.pem;
 
-### Security headers
+    # Security headers
     add_header X-Content-Type-Options   "nosniff" always;
     add_header X-Frame-Options          "SAMEORIGIN" always;
     add_header Referrer-Policy          "strict-origin-when-cross-origin" always;
@@ -55,10 +55,12 @@ server {
     # 31536000 once stable; "; includeSubDomains" needs HTTPS on all subdomains.
     add_header Strict-Transport-Security "max-age=300" always;
 
+    # Hide Nginx version in error pages and Server HTTP header to avoid vulnerabilities
     server_tokens off;
+
     autoindex     off;
 
-### Blocked paths
+    # Blocked paths (redirect to 404.html)
     error_page 403 404 /404.html;
 
     location ^~ /backend/ {
@@ -77,7 +79,7 @@ server {
         return 404;
     }
 
-### API backend — Node primary, PHP fallback
+    # API backend — Node primary, PHP fallback
     location ^~ /api/ {
         proxy_pass http://127.0.0.1:3000;
         proxy_http_version 1.1;
@@ -102,12 +104,12 @@ server {
         fastcgi_pass unix:/run/php/php-fpm.sock;
     }
 
-### Static files
+    # Static files
     location / {
         try_files $uri $uri/ $uri.html =404;
     }
 
-### Error page
+    # Error page
     location = /404.html {
         internal;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nibula",
-  "version": "1.6.2",
+  "version": "2.0.1",
   "description": "A beginner-friendly static site generator built on Eleventy that stays close to vanilla HTML, CSS and JS — with a page-management CLI, an optional PHP backend, and SEO files generated for you.",
   "keywords": [
     "11ty",

package/src/frontend/components/not-found.njk

@@ -0,0 +1,4 @@
+<div class="fade-in not-found">
+  <h1>Oops! Page not found</h1>
+  <a href="/">Return to homepage</a>
+</div>

package/src/frontend/routes/404.njk

@@ -0,0 +1,10 @@
+---
+title: "404"
+permalink: "404.html"
+layout: base.njk
+---
+
+<!-- !IMPORTANT -->
+<!-- To keep order, the best practice is to create a new component.njk file in components/ and include it here-->
+
+{% include "not-found.njk" ignore missing %}

package/src/frontend/routes/index.njk

@@ -0,0 +1,10 @@
+---
+title: "homepage"
+permalink: "/"
+layout: base.njk
+---
+
+<!-- !IMPORTANT -->
+<!-- To keep order, the best practice is to create a new component.njk file in components/ and include it here-->
+
+{% include "welcome.njk" ignore missing %}

package/src/frontend/ts/global.ts

@@ -1,5 +1,4 @@
-// import { initExampleModule } from "/exampleModule";
-import { initExampleModule } from "./modules/exampleModule"
+// import { initExampleModule } from "./modules/exampleModule"
 
 function initGlobal() {
     // initExampleModule();

package/tools/config/messages.json

@@ -26,14 +26,6 @@
     "renameFailed": "[error] could not rename page files: {error}",
     "deleteFailed": "[error] {path}: {error}"
   },
-  "components": {
-    "fileMissing": "[skip] not found: {path}",
-    "anchorMissing": "[skip] no {anchor} anchor in {file}",
-    "blockAdded": "[updated] page block added for \"{name}\"",
-    "blockMissing": "[skip] page block for \"{name}\" not found",
-    "blockRemoved": "[cleaned] page block removed for \"{name}\"",
-    "blockRenamed": "[renamed] page block \"{source}\" \u2192 \"{destination}\""
-  },
   "pagesData": {
       "fileMissing": "[skip] not found: {path}",
       "invalidStructure": "[error] {file} must contain an object of pages",

package/tools/config/settings.json

@@ -13,7 +13,6 @@
     "stylePages": "src/frontend/scss/pages",
     "pagesData": "src/frontend/data/pages.json",
     "siteData": "src/frontend/data/site.json",
-    "pageComponents": "src/frontend/layouts/page-components.njk",
     "templates": "tools/res/templates"
   },
   "languages": {
@@ -94,11 +93,6 @@
       }
     }
   },
-  "pageComponents": {
-    "anchor": "{% else %}",
-    "condition": "{% elif title == \"{camelName}\" %}",
-    "include": "{% include \"component-name.njk\" ignore missing %}"
-  },
   "frontMatter": {
     "title": "title: \"{camelName}\"",
     "permalink": "permalink: \"/{pageName}/\""

package/tools/lib/pageActions.js

@@ -7,7 +7,6 @@ const { formatText } = require('./text');
 const { languageSettings } = require('./project');
 const { getPageArtifacts, pageExists } = require('./pageArtifacts');
 const { readPagesData, addPageData, removePageData, renamePageData } = require('./pagesData');
-const { addPageBlock, removePageBlock, renamePageBlock } = require('./pageComponents');
 
 const FRONT_MATTER_PATTERNS = Object.freeze({
     title:     /^title:.*$/m,
@@ -62,7 +61,6 @@ function addPage(pageName) {
         return;
     }
 
-    addPageBlock(pageName);
     addPageData(pageName);
 }
 
@@ -104,7 +102,6 @@ function renamePage(oldName, newName) {
         return;
     }
 
-    renamePageBlock(oldName, newName);
     renamePageData(oldName, newName);
 }
 
@@ -134,7 +131,6 @@ function removePage(pageName) {
         }
     }
 
-    removePageBlock(pageName);
     removePageData(pageName);
 
     const sourceDirectories = [source.style, source.script, source.route].map(file => path.dirname(file));

package/tools/lib/paths.js

@@ -46,7 +46,6 @@ const PATHS = Object.freeze({
     get stylePages()       { return resolveFromProject(settings.paths.stylePages); },
     get siteData()         { return resolveFromProject(settings.paths.siteData); },
     get pagesData()        { return resolveFromProject(settings.paths.pagesData); },
-    get pageComponents()   { return resolveFromProject(settings.paths.pageComponents); },
     get templates()        { return resolveFromPackage(settings.paths.templates); },
 });
 

package/tools/lib/validation.js

@@ -13,7 +13,6 @@ function requiredFiles() {
         { label: settings.paths.packageJson,     path: PATHS.packageJson },
         { label: settings.paths.siteData,        path: PATHS.siteData },
         { label: settings.paths.pagesData,       path: PATHS.pagesData },
-        { label: settings.paths.pageComponents,  path: PATHS.pageComponents },
         { label: message('validation.templatesLabel'), path: PATHS.templates },
     ];
 }

package/tools/res/templates/template.njk

@@ -1,9 +1,10 @@
 ---
 title: ""
 permalink: ""
-layout: page-components.njk
+layout: base.njk
 ---
 
 <!-- !IMPORTANT -->
-<!-- DO NOT ADD ANYTHING HERE -->
-<!-- You should create a new component.njk into src/frontend and include that in layouts/page-components.njk -->
+<!-- To keep order, the best practice is to create a new component.njk file in components/ and include it here-->
+
+{% include "component.njk" ignore missing %}

package/src/frontend/404.njk

@@ -1,17 +0,0 @@
----
-title: "404"
-permalink: 404.html
-layout: base.njk
----
-
-<!-- !IMPORTANT -->
-<!-- This is the only page that you need to modify statically -->
-
-<div class="fade-in not-found">
-  <h1>Oops! Page not found</h1>
-  <a href="/">Return to homepage</a>
-</div>
-
-
-{# You can also add the includes you need here below
-{% include "component.njk" %} #}

package/src/frontend/index.njk

@@ -1,9 +0,0 @@
----
-title: homepage
-permalink: /
-layout: page-components.njk
----
-
-<!-- !IMPORTANT -->
-<!-- DO NOT ADD ANYTHING HERE -->
-<!-- You should create a new component.njk into src/components and include that in layouts/page-components.njk -->

package/src/frontend/layouts/page-components.njk

@@ -1,14 +0,0 @@
----
-layout: base.njk
----
-
-<!-- NJK (HTML) components per page -->
- 
-{% if title == "homepage" %}
-{% include "welcome.njk" ignore missing %}
-
-{% else %}
-<!-- You should not touch this else statement -->
-{% include "404/_404.njk" %}
-{{ content | safe }}
-{% endif %}

package/tools/lib/pageComponents.js

@@ -1,88 +0,0 @@
-const path = require('path');
-const settings = require('../config/settings.json');
-const { PATHS } = require('./paths');
-const { exists, readText, writeText } = require('./files');
-const { log } = require('./logger');
-const { toCamelCase, formatText } = require('./text');
-
-const EXTRA_BLANK_LINES_PATTERN = /\n\s*\n\s*\n/g;
-const BLANK_LINES = '\n\n';
-const ANCHOR = settings.pageComponents.anchor;
-
-function blockPattern(camelName) {
-    return new RegExp(
-        `[ \\t]*\\{%\\s*elif\\s+title\\s*==\\s*"${camelName}"\\s*%\\}[\\s\\S]*?(?=[ \\t]*\\{%\\s*(?:elif|else|endif))`
-    );
-}
-
-function conditionFor(camelName) {
-    return formatText(settings.pageComponents.condition, { camelName });
-}
-
-function readPageComponents() {
-    if (!exists(PATHS.pageComponents)) {
-        log('components.fileMissing', { path: PATHS.pageComponents });
-        return null;
-    }
-    return readText(PATHS.pageComponents);
-}
-
-function writePageComponents(content) {
-    writeText(PATHS.pageComponents, content);
-}
-
-function addPageBlock(pageName) {
-    const content = readPageComponents();
-    if (content === null) return;
-
-    const camelName = toCamelCase(pageName);
-    const condition = conditionFor(camelName);
-    if (content.includes(condition)) return;
-
-    if (!content.includes(ANCHOR)) {
-        log('components.anchorMissing', { anchor: ANCHOR, file: path.basename(PATHS.pageComponents) });
-        return;
-    }
-
-    const block = `${condition}\n${settings.pageComponents.include}\n\n`;
-
-    writePageComponents(content.replace(ANCHOR, `${block}${ANCHOR}`));
-    log('components.blockAdded', { name: camelName });
-}
-
-function removePageBlock(pageName) {
-    const content = readPageComponents();
-    if (content === null) return;
-
-    const camelName = toCamelCase(pageName);
-    if (!blockPattern(camelName).test(content)) {
-        log('components.blockMissing', { name: camelName });
-        return;
-    }
-
-    const updated = content
-        .replace(blockPattern(camelName), '')
-        .replace(EXTRA_BLANK_LINES_PATTERN, BLANK_LINES);
-
-    writePageComponents(updated);
-    log('components.blockRemoved', { name: camelName });
-}
-
-function renamePageBlock(oldName, newName) {
-    const content = readPageComponents();
-    if (content === null) return;
-
-    const oldCamelName = toCamelCase(oldName);
-    const newCamelName = toCamelCase(newName);
-    const oldCondition = conditionFor(oldCamelName);
-
-    if (!content.includes(oldCondition)) {
-        log('components.blockMissing', { name: oldCamelName });
-        return;
-    }
-
-    writePageComponents(content.replace(oldCondition, conditionFor(newCamelName)));
-    log('components.blockRenamed', { source: oldCamelName, destination: newCamelName });
-}
-
-module.exports = { addPageBlock, removePageBlock, renamePageBlock };