nibula 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.1] - 2026-08-08
+
+### Added
+- `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
+- `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

package/docs/Components.md

@@ -14,7 +14,7 @@ src/frontend/components/
 │   ├── header.njk
 │   └── footer.njk
 ├── modals/
-│   └── privacyModal.njk # You can move it to a modals/subfolder
+│   └── privacyModal.njk
 ├── not-found.njk
 ├── welcome.njk
 ```
@@ -25,7 +25,7 @@ Components are included in the page that renders them. Open the page's file in `
 
 ### example-page.njk <small>(`src/frontend/routes/`)</small>
 
-```js
+```njk
 ---
 title: "examplePage"
 permalink: "/example-page/"
@@ -49,7 +49,7 @@ Writing HTML directly in the route works too, and is perfectly fine for a short
 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" %}
@@ -62,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 }}">
@@ -108,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>
 ```
 
@@ -131,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,26 +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 the page's own file, `src/frontend/routes/my-page.njk`:
+The route is created empty. Write your HTML in its body, or include components — see the **Components** DOC file.
 
-```njk
----
-title: "myPage"
-permalink: "/my-page/"
-layout: base.njk
----
+## URL and title
 
-{% include "my-component.njk" %}
-```
+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.
 
-See **Components** DOC file for more info
+## Layout
 
-## URL and title
+`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)
 
@@ -52,26 +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": []
-      }
-    }
-```
-
-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.
+| `/company/about/team/` | `/company/about/team/` | `routes/team.njk` |

package/docs/Head and SEO.md

@@ -15,6 +15,7 @@ Global settings live in `src/frontend/data/site.json` and are available everywhe
   "lang": "en",
   "author": "Name and surname",
   "theme": "dark",
+  "theme_color": "#2a2150",
   "logo": "/assets/brand/logo.svg",
   "legal": {
     "privacy": "",
@@ -74,6 +75,8 @@ Per-page settings live in `src/frontend/data/pages.json`, available via `{{ page
 | `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:
@@ -120,12 +123,24 @@ 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 in `src/frontend/indexing/` and are publicly reachable (they must not be blocked by the server config).

package/docs/Project structure.md

@@ -16,7 +16,7 @@ your-project/
     ├── backend/          # REST API — see docs/Backend.md
     └── frontend/
         ├── assets/       # Images, fonts, brand files
-            └── brand/    # Favicons, logo etc
+        │   └── brand/    # Favicons, logo etc
         ├── components/   # Reusable .njk fragments
         │   └── global/   # Header and footer, included in every page
         ├── data/         # site.json and pages.json
@@ -44,6 +44,7 @@ your-project/
 | 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
@@ -58,6 +59,7 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nibula",
-  "version": "2.0.0",
+  "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/ts/global.ts

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