nibula 1.6.1 → 2.0.0

package/.eleventy.js

@@ -27,12 +27,16 @@ 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");
 
   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",
 

package/CHANGELOG.md

@@ -5,6 +5,89 @@ 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).
 
+## [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`.
+
 ## [1.6.1] - 2026-08-06
 
 ### Fixed

package/bin/create.js

@@ -33,6 +33,11 @@ const BACKEND = Object.freeze({
     PHP:  'php',
 });
 
+const COMMENT_STYLE = Object.freeze({
+    SLASH: { open: '// ', close: '' },
+    NJK:   { open: '{# ', close: ' #}' },
+});
+
 // ── CHOICES ──────────────────────────────────────────────────────────────────
 
 const LANGUAGE_CHOICES = [
@@ -88,14 +93,16 @@ const BACKEND_SKIP_DIRS = new Set(['node_modules', 'cache', '.git']);
 
 const ALL_FRAMEWORKS = Object.values(FRAMEWORK).filter(f => f !== FRAMEWORK.NONE);
 
+const SCSS_FRAMEWORK_PREFIX = 'modules/frameworks/';
+
+// Markers are substrings matched against whole lines, never full lines, so the
+// surrounding syntax (Nunjucks url filter, passthrough copy mapping) can change
+// without breaking the scaffolder.
 const FRAMEWORKS = {
     [FRAMEWORK.BOOTSTRAP]: {
         scss:     'bootstrap',
-        njk:      ['<script src="/js/bootstrap.bundle.min.js" defer></script>'],
-        eleventy: [
-            '"node_modules/bootstrap/dist/js/bootstrap.bundle.min.js": "js/bootstrap.bundle.min.js",',
-            '"node_modules/bootstrap-icons/font/fonts": "css/fonts",',
-        ],
+        njk:      ['/js/bootstrap.bundle.min.js'],
+        eleventy: ['bootstrap/dist/js/bootstrap.bundle.min.js', 'bootstrap-icons/font/fonts'],
     },
     [FRAMEWORK.BULMA]: {
         scss:     'bulma',
@@ -104,19 +111,13 @@ const FRAMEWORKS = {
     },
     [FRAMEWORK.FOUNDATION]: {
         scss:     'foundation',
-        njk:      ['<script src="/js/foundation.min.js" defer></script>'],
-        eleventy: ['"node_modules/foundation-sites/dist/js/foundation.min.js": "js/foundation.min.js",'],
+        njk:      ['/js/foundation.min.js'],
+        eleventy: ['foundation-sites/dist/js/foundation.min.js'],
     },
     [FRAMEWORK.UIKIT]: {
         scss:     'uikit',
-        njk:      [
-            '<script src="/js/uikit.min.js" defer></script>',
-            '<script src="/js/uikit-icons.min.js" defer></script>',
-        ],
-        eleventy: [
-            '"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",',
-        ],
+        njk:      ['/js/uikit.min.js', '/js/uikit-icons.min.js'],
+        eleventy: ['uikit/dist/js/uikit.min.js', 'uikit/dist/js/uikit-icons.min.js'],
     },
     [FRAMEWORK.NONE]: {
         scss:     null,
@@ -189,10 +190,6 @@ function logAdd(name) {
     log(`${color.green}+${color.reset} ${name}`);
 }
 
-function escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
 function copyRecursive(src, dest, exclude = []) {
     const stat = fs.statSync(src);
     if (stat.isDirectory()) {
@@ -250,22 +247,60 @@ function copyBackend(src, dest, backend) {
     }
 }
 
-function slashComment(content, line) {
-    content = content.replace(new RegExp(`^([ \\t]*)// (${escapeRegex(line)})$`, 'gm'), '$1$2');
-    return content.replace(new RegExp(`^([ \\t]*)(${escapeRegex(line)})$`, 'gm'), '$1// $2');
+function splitLine(line) {
+    const body = line.trim();
+    if (!body) return { indent: line, body: '', trailing: '' };
+
+    const start = line.indexOf(body);
+    return {
+        indent:   line.slice(0, start),
+        body,
+        trailing: line.slice(start + body.length),
+    };
+}
+
+function uncommentLine(line, style) {
+    const { indent, body, trailing } = splitLine(line);
+    if (!body.startsWith(style.open)) return line;
+
+    let inner = body.slice(style.open.length);
+    if (style.close) {
+        if (!inner.endsWith(style.close)) return line;
+        inner = inner.slice(0, -style.close.length);
+    }
+
+    return indent + inner + trailing;
+}
+
+function commentLine(line, style) {
+    const bare = uncommentLine(line, style);
+    const { indent, body, trailing } = splitLine(bare);
+    if (!body) return line;
+
+    return indent + style.open + body + style.close + trailing;
+}
+
+function mapMarkedLines(content, marker, style, transform) {
+    return content
+        .split('\n')
+        .map(line => (line.includes(marker) ? transform(line, style) : line))
+        .join('\n');
+}
+
+function slashComment(content, marker) {
+    return mapMarkedLines(content, marker, COMMENT_STYLE.SLASH, commentLine);
 }
 
-function slashUncomment(content, line) {
-    return content.replace(new RegExp(`^([ \\t]*)// (${escapeRegex(line)})$`, 'gm'), '$1$2');
+function slashUncomment(content, marker) {
+    return mapMarkedLines(content, marker, COMMENT_STYLE.SLASH, uncommentLine);
 }
 
-function njkComment(content, line) {
-    content = content.split(`{# ${line} #}`).join(line);
-    return content.split(line).join(`{# ${line} #}`);
+function njkComment(content, marker) {
+    return mapMarkedLines(content, marker, COMMENT_STYLE.NJK, commentLine);
 }
 
-function njkUncomment(content, line) {
-    return content.split(`{# ${line} #}`).join(line);
+function njkUncomment(content, marker) {
+    return mapMarkedLines(content, marker, COMMENT_STYLE.NJK, uncommentLine);
 }
 
 function installDependencies(backend) {
@@ -323,14 +358,14 @@ function installDependencies(backend) {
 function applyFramework(framework) {
     const config = FRAMEWORKS[framework];
 
-    const globalScssPath = path.join(targetDir, 'src/frontend/scss/modules/_global.scss');
+    const globalScssPath = path.join(targetDir, 'src/frontend/scss/_global.scss');
     if (fs.existsSync(globalScssPath)) {
         let content = fs.readFileSync(globalScssPath, 'utf8');
         ALL_FRAMEWORKS.forEach(fw => {
-            content = slashComment(content, `@import "../modules/frameworks/${fw}";`);
+            content = slashComment(content, `${SCSS_FRAMEWORK_PREFIX}${fw}`);
         });
         if (config.scss) {
-            content = slashUncomment(content, `@import "../modules/frameworks/${config.scss}";`);
+            content = slashUncomment(content, `${SCSS_FRAMEWORK_PREFIX}${config.scss}`);
         }
         fs.writeFileSync(globalScssPath, content);
     }
@@ -339,9 +374,9 @@ function applyFramework(framework) {
     if (fs.existsSync(baseNjkPath)) {
         let content = fs.readFileSync(baseNjkPath, 'utf8');
         ALL_FRAMEWORKS.forEach(fw => {
-            FRAMEWORKS[fw].njk.forEach(line => { content = njkComment(content, line); });
+            FRAMEWORKS[fw].njk.forEach(marker => { content = njkComment(content, marker); });
         });
-        config.njk.forEach(line => { content = njkUncomment(content, line); });
+        config.njk.forEach(marker => { content = njkUncomment(content, marker); });
         fs.writeFileSync(baseNjkPath, content);
     }
 
@@ -349,9 +384,9 @@ function applyFramework(framework) {
     if (fs.existsSync(eleventyPath)) {
         let content = fs.readFileSync(eleventyPath, 'utf8');
         ALL_FRAMEWORKS.forEach(fw => {
-            FRAMEWORKS[fw].eleventy.forEach(line => { content = slashComment(content, line); });
+            FRAMEWORKS[fw].eleventy.forEach(marker => { content = slashComment(content, marker); });
         });
-        config.eleventy.forEach(line => { content = slashUncomment(content, line); });
+        config.eleventy.forEach(marker => { content = slashUncomment(content, marker); });
         fs.writeFileSync(eleventyPath, content);
     }
 }

package/bin/delegate.js

@@ -10,6 +10,7 @@ const ENTRY_FILE = path.join('bin', 'nibula.js');
 const PACKAGE_FILE = 'package.json';
 const LOCAL_FLAG = 'NIBULA_LOCAL';
 const LOCAL_FLAG_VALUE = '1';
+const GLOBAL_VERSION_FLAG = 'NIBULA_GLOBAL_VERSION';
 
 const globalVersion = require(`../${PACKAGE_FILE}`).version;
 
@@ -49,7 +50,7 @@ function delegateToLocal(projectRoot) {
     const result = spawnSync(process.execPath, [localEntry, ...process.argv.slice(2)], {
         stdio: 'inherit',
         cwd: process.cwd(),
-        env: { ...process.env, [LOCAL_FLAG]: LOCAL_FLAG_VALUE },
+        env: { ...process.env, [LOCAL_FLAG]: LOCAL_FLAG_VALUE, [GLOBAL_VERSION_FLAG]: globalVersion },
     });
 
     process.exit(result.status ?? 0);

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,37 +11,38 @@ 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
+├── 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" %}
+---
+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
 

package/docs/Creating pages.md

@@ -16,11 +16,16 @@ For a page named `my-page`:
 ## 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:
+2. Include it in the page's own file, `src/frontend/routes/my-page.njk`:
 
 ```njk
-{% elif title == "myPage" %}
-  {% include "my-component.njk" ignore missing %}
+---
+title: "myPage"
+permalink: "/my-page/"
+layout: base.njk
+---
+
+{% include "my-component.njk" %}
 ```
 
 See **Components** DOC file for more info
@@ -36,8 +41,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
 ---
 ```
 
@@ -67,4 +72,6 @@ The CLI creates a stub entry in `src/frontend/data/pages.json`. Fill it in:
         "js": []
       }
     }
-```
+```
+
+The `seo.title` and `seo.description` you write here are also what the page shows up as in `llms.txt`, so a page left with the placeholder description will advertise itself that way to AI crawlers.

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
 
@@ -19,7 +19,6 @@ Global settings live in `src/frontend/data/pages.json` and are available everywh
   "legal": {
     "privacy": "",
     "cookie": "",
-    "cookieControls": "",
     "terms": "",
     "copyright": {
       "year": "2026",
@@ -41,7 +40,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,10 +67,10 @@ 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 |
 
@@ -129,12 +128,14 @@ The three favicon tags are hardcoded in `base.njk`. To change the icons, replace
 
 ## 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` |
 
-To customize, edit `src/frontend/llms.njk` or `src/frontend/robots.njk` directly.
+`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 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,63 @@
+# 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` |
+| 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
+- `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

@@ -31,7 +31,7 @@ body {
 
 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/modules/`)</small>
+### _root.scss <small>(`src/frontend/scss/`)</small>
 ```scss
 $header-height: 10vh;
 
@@ -51,6 +51,8 @@ You can create subfolders if you want to refactor the structure, but be sure to
 ```scss
 @use '../../root' as root;
 
+@import '../../global';
+
 body {
   background-color: root.$primary;
 }
@@ -97,19 +99,19 @@ To enable/disable them you have to modify 3 files around the project by just com
 
 ```html
 {# Bootstrap JS #}
-<script src="/js/bootstrap.bundle.min.js" defer></script>
+<script src="{{ '/js/bootstrap.bundle.min.js' | url }}" defer></script>
 
 {# Foundation JS #}
-{# <script src="/js/foundation.min.js" defer></script> #}
+{# <script src="{{ '/js/foundation.min.js' | url }}" defer></script> #}
 
 {# UIkit JS #}
-{# <script src="/js/uikit.min.js" defer></script> #}
-{# <script src="/js/uikit-icons.min.js" defer></script> #}
+{# <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.config.js
+### 3. .eleventy.js <small>(project root)</small>
 
 ```javascript
 eleventyConfig.addPassthroughCopy({
@@ -128,7 +130,9 @@ eleventyConfig.addPassthroughCopy({
 });
 ```
 
-> ⚠️ Changes to `eleventy.config.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.1",
+  "version": "2.0.0",
   "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/layouts/base.njk

@@ -109,7 +109,6 @@
         ╚══════════════════╝#}
 
         {# Framework — uncomment the one you are using #}
-        
         {# Bootstrap JS #}
         <script src="{{ '/js/bootstrap.bundle.min.js' | url }}" defer></script>
 

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/tools/cli/ui.js

@@ -15,12 +15,14 @@ const BOX_VERTICAL = '\u2502';
 const NEW_LINE = '\n';
 const SPACE = ' ';
 
-const LOCAL_FLAG = 'NIBULA_LOCAL';
-const LOCAL_FLAG_VALUE = '1';
+const GLOBAL_VERSION_FLAG = 'NIBULA_GLOBAL_VERSION';
 const TITLE_PADDING = 2;
 
-const TITLE_SUFFIX = process.env[LOCAL_FLAG] === LOCAL_FLAG_VALUE
-    ? ` (local v${require('../../package.json').version})`
+const LOCAL_VERSION = require('../../package.json').version;
+const GLOBAL_VERSION = process.env[GLOBAL_VERSION_FLAG];
+
+const TITLE_SUFFIX = GLOBAL_VERSION && GLOBAL_VERSION !== LOCAL_VERSION
+    ? ` (local v${LOCAL_VERSION})`
     : '';
 
 const PLAIN_TITLE = `${BOX_TITLE}${TITLE_SUFFIX}`;
@@ -55,8 +57,6 @@ function centeredTitle() {
     const left = SPACE.repeat(Math.ceil(padding / 2));
     const right = SPACE.repeat(Math.floor(padding / 2));
 
-    if (!TITLE_SUFFIX) return `${left}${BOX_TITLE}${right}`;
-
     const suffix = `${color.dim}${TITLE_SUFFIX}${color.reset}${color[COLORS.box]}${color.bold}`;
     return `${left}${BOX_TITLE}${suffix}${right}`;
 }

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 };