nibula 2.0.2 → 2.2.0

package/.eleventy.js

@@ -1,17 +1,30 @@
-const esbuild = require("esbuild");
-const glob = require("glob");
+const { RenderPlugin } = require("@11ty/eleventy");
+const markdownItAnchor = require("markdown-it-anchor");
+const markdownItAttrs = require("markdown-it-attrs");
 const Image = require("@11ty/eleventy-img");
 const fs = require("fs");
 const path = require("path");
 
 const OUTPUT_DIR = "out";
+const TEMPLATE_ENGINE = "njk";
+const ANCHOR_LEVELS = [2, 3, 4];
+const ANCHOR_PERMALINK_SYMBOL = "#";
+const ANCHOR_PERMALINK_PLACEMENT = "after";
+
+const MARKDOWN_BASE_PATH = "src/frontend/components/";
 
 module.exports = function (eleventyConfig) {
 
+  // ---------------------------------------------------------------------------
+  // Utilities
+  // ---------------------------------------------------------------------------
+
   function copyRecursiveSync(src, dest) {
     if (!fs.existsSync(src)) return;
-    if (src.includes('.git')) return;
+    if (src.includes(".git")) return;
+
     const stat = fs.statSync(src);
+
     if (stat.isDirectory()) {
       fs.mkdirSync(dest, { recursive: true });
       for (const child of fs.readdirSync(src)) {
@@ -23,18 +36,47 @@ module.exports = function (eleventyConfig) {
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // Plugins & markdown
+  // ---------------------------------------------------------------------------
+
+  eleventyConfig.addPlugin(RenderPlugin);
+
+  eleventyConfig.amendLibrary("md", (markdownLibrary) => {
+    markdownLibrary
+      .use(markdownItAnchor, {
+        level: ANCHOR_LEVELS,
+        permalink: markdownItAnchor.permalink.linkInsideHeader({
+          symbol: ANCHOR_PERMALINK_SYMBOL,
+          placement: ANCHOR_PERMALINK_PLACEMENT,
+        }),
+      })
+      .use(markdownItAttrs);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Events
+  // ---------------------------------------------------------------------------
+
   eleventyConfig.on("eleventy.before", () => {
     copyRecursiveSync("src/backend", `${OUTPUT_DIR}/backend`);
   });
 
+  // ---------------------------------------------------------------------------
+  // Passthrough copy
+  // ---------------------------------------------------------------------------
+
+  // Project assets
+  eleventyConfig.addPassthroughCopy("src/frontend/assets");
+  eleventyConfig.addPassthroughCopy("src/frontend/robots.txt");
+
+  // Hosting files
   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");
 
+  // node_modules dependencies
   eleventyConfig.addPassthroughCopy({
     // Bootstrap
     "node_modules/bootstrap/dist/js/bootstrap.bundle.min.js": "js/bootstrap.bundle.min.js",
@@ -50,8 +92,14 @@ module.exports = function (eleventyConfig) {
     // Bulma — CSS only, no JS passthrough needed
   });
 
+  // ---------------------------------------------------------------------------
+  // Shortcodes
+  // ---------------------------------------------------------------------------
+
+  eleventyConfig.addFilter("markdownPath", (name) => `${MARKDOWN_BASE_PATH}${name}`);
+
   eleventyConfig.addShortcode("image", async function (src, alt) {
-    let metadata = await Image(src, {
+    const metadata = await Image(src, {
       widths: [320, 480, 720, 1280, 1920, 2048, 2560, 3840, 4096, 7680],
       formats: ["webp", "jpeg"],
       outputDir: `${OUTPUT_DIR}/assets/images/`,
@@ -66,15 +114,27 @@ module.exports = function (eleventyConfig) {
     });
   });
 
+  // ---------------------------------------------------------------------------
+  // Watch targets & dev server
+  // ---------------------------------------------------------------------------
+
   eleventyConfig.addWatchTarget("./src/frontend/scss");
   eleventyConfig.addWatchTarget("./src/frontend/routes");
   eleventyConfig.addWatchTarget("./src/frontend/data");
+  eleventyConfig.addWatchTarget("./src/frontend/components");
 
   eleventyConfig.setServerOptions({
-  watch: [`${OUTPUT_DIR}/js/**/*.js`]
+    watch: [`${OUTPUT_DIR}/js/**/*.js`],
   });
 
+  // ---------------------------------------------------------------------------
+  // Directory configuration
+  // ---------------------------------------------------------------------------
+
   return {
+    markdownTemplateEngine: TEMPLATE_ENGINE,
+    htmlTemplateEngine: TEMPLATE_ENGINE,
+
     dir: {
       input: "src/frontend",
       output: OUTPUT_DIR,

package/CHANGELOG.md

@@ -5,6 +5,114 @@ 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.2.0] - 2026-08-18
+
+### Added
+- **Markdown rendered with `renderFile` is styled out of the box.**
+  `src/frontend/scss/modules/_markdown.scss` carries GitHub's Markdown layout —
+  tables, code blocks, blockquotes, heading spacing — scoped to a
+  `.markdown-body` container. Markdown produces plain HTML with no classes, so a
+  rendered `.md` came out as unstyled text regardless of the CSS framework in the
+  project. Colours follow `data-theme`, and the background is transparent so the
+  block sits on the page instead of on a panel of its own.
+- The commented `renderFile` example in the route template now shows the
+  `.markdown-body` wrapper, which is what applies the styling.
+
+### Changed
+- `docs/Components.md` documents the wrapper as part of the `renderFile` line,
+  and no longer says Markdown comes out unstyled: `{.class}` is now for adding
+  your framework's classes to specific elements, not for making the content
+  presentable in the first place.
+- `docs/Styling with SCSS.md` lists `_markdown.scss` among the pre-existing
+  modules, noting that it is generated rather than hand-written and that its
+  import has to stay after the framework for its table and code block rules to
+  win.
+
+### Notes
+- The styling lands in newly created projects only. To adopt it in an existing
+  one, copy `src/frontend/scss/modules/_markdown.scss` and import it in
+  `_global.scss` after the framework, then wrap your `renderFile` calls in
+  `<article class="markdown-body">`.
+
+## [2.1.0] - 2026-08-17
+
+### Added
+- **The assistant asks which layout a new page should use.** Any `.njk` file in
+  `src/frontend/layouts/` is offered in an arrow-key menu, and the chosen one is
+  written into the route's front matter. Before, every page was created with
+  `base.njk` and the documentation had to remind you to change it by hand — the
+  assistant wrote a value the reader was then expected to correct. With a single
+  layout in the folder the menu is skipped, so nothing changes for a project that
+  has not added one; with none, the front matter is left untouched.
+- `askChoice` in `tools/cli/prompt.js`: the arrow-key menu the scaffolder already
+  used, available to the assistant as well.
+- **Markdown files can be rendered inside a page.** `markdown-it-anchor` and
+  `markdown-it-attrs` are installed and preconfigured, and Eleventy's
+  `RenderPlugin` is registered, so a `.md` file in `src/frontend/components/`
+  can be pulled into a route with `renderFile`. Headings from level 2 down get
+  an `id` and a `#` link, and `{.class}` applies a CSS class inline — markdown
+  produces plain HTML, so without a way to set classes the output carries none of
+  the project's framework styling.
+- A `markdownPath` filter that prefixes the components folder, so a route writes
+  `"your-file.md" | markdownPath` and not the full path from the project root.
+  `renderFile` resolves paths from the working directory, unlike `include`, which
+  resolves them from the components folder.
+- The template new pages are created from carries a commented `renderFile`
+  example next to the component one, with the data argument included:
+  `renderFile` does not inherit the page context, so a `.md` that reads `site.*`
+  renders those values empty unless the data is passed explicitly.
+
+### Changed
+- **`tools/cli/prompt.js` creates a readline interface per question** instead of
+  holding one open for the whole session. The session-wide interface kept its own
+  keypress listener on stdin, which would have fought with the raw-mode listener
+  the arrow-key menu needs: both would have received every key, so arrows moved
+  the readline cursor and Enter fired its `line` event.
+- **`markdownTemplateEngine` and `htmlTemplateEngine` are set to Nunjucks.**
+  Eleventy defaults `.md` files to Liquid, so a markdown file containing
+  `{{ site.title }}` was processed by a different template engine than every
+  other file in the project — working for the simple cases and silently not for
+  the rest.
+- `src/frontend/components` is now a watch target. Eleventy tracks `.njk`
+  includes as template dependencies, but a `.md` read through `renderFile` is
+  invisible to it, so editing one changed nothing until the route itself was
+  saved.
+- `.eleventy.js` is grouped into labelled sections, with plugins and markdown
+  configuration ahead of the build event and the passthrough copies.
+- **Documentation is written for readers who are new to this.** The docs assumed
+  vocabulary a beginner does not have yet. `Deploy.md` opens with a question that
+  routes the reader by backend, and explains what shared hosting, a VPS, systemd,
+  an HTTPS certificate and `screen` actually are; the Node section now separates
+  trying the backend out from setting it up to survive a reboot, which read as
+  five equal steps before. `Head and SEO.md` starts from what the `<head>` is and
+  why there are two data files, and drops the unexplained jargon — canonical,
+  JSON-LD, noindex. `Components.md` documents markdown from what Markdown is,
+  with each part of the `renderFile` line explained rather than assumed.
+- `Project structure.md` lists `components/` as the home of `.md` content, and
+  `Creating pages.md` describes both commented examples a new route carries.
+
+### Fixed
+- `Deploy.md` told the reader to open the Nginx site file with `nano` and how to
+  save it, without ever saying what to paste into it. The step now names the
+  edited `nginx.conf` as the source.
+
+### Removed
+- **The dead language switch in the scaffolder.** `bin/create.js` commented and
+  uncommented a `glob.sync` line for the JavaScript and TypeScript entry points,
+  but that line has not existed in `.eleventy.js` since bundling moved to
+  `tools/buildJs.js`, so the two markers matched nothing and the function ran as
+  a no-op. Entry points are collected from both language folders and resolved
+  against the filesystem, which makes the switch unnecessary: the folder that
+  does not exist contributes nothing.
+- Unused `esbuild` and `glob` imports from `.eleventy.js`. Both are still real
+  dependencies of `tools/buildJs.js`, which is where they are used.
+
+### Notes
+- The markdown setup lands in newly created projects only. To adopt it in an
+  existing one, install `markdown-it-anchor` and `markdown-it-attrs` and copy the
+  plugin block, the `markdownPath` filter and the two template engine settings
+  from the current `.eleventy.js`.
+
 ## [2.0.2] - 2026-08-08
 
 ### Fixed

package/bin/create.js

@@ -126,13 +126,6 @@ const FRAMEWORKS = {
     },
 };
 
-// ── LANGUAGE CONFIG ───────────────────────────────────────────────────────────
-
-const LANGUAGE_ELEVENTY = Object.freeze({
-    jsEntry: 'const entryPoints = glob.sync("src/frontend/js/pages/*.js");',
-    tsEntry: 'const entryPoints = glob.sync("src/frontend/ts/pages/*.ts");',
-});
-
 // ── GENERATED FILE CONTENTS ───────────────────────────────────────────────────
 
 const GITIGNORE_CONTENT = `
@@ -170,6 +163,8 @@ const PROJECT_PACKAGE = {
         'bulma':              '^1.0.4',
         'foundation-sites':   '^6.9.0',
         'glob':               '^13.0.6',
+        'markdown-it-anchor': '^9.2.1',
+        'markdown-it-attrs':  '^5.0.1',
         'uikit':              '^3.25.13',
     },
     devDependencies: {
@@ -391,23 +386,6 @@ function applyFramework(framework) {
     }
 }
 
-function applyLanguage(language) {
-    const eleventyPath = path.join(targetDir, '.eleventy.js');
-    if (!fs.existsSync(eleventyPath)) return;
-
-    let content = fs.readFileSync(eleventyPath, 'utf8');
-
-    if (language === LANGUAGE.TYPESCRIPT) {
-        content = slashComment(content,   LANGUAGE_ELEVENTY.jsEntry);
-        content = slashUncomment(content, LANGUAGE_ELEVENTY.tsEntry);
-    } else {
-        content = slashUncomment(content, LANGUAGE_ELEVENTY.jsEntry);
-        content = slashComment(content,   LANGUAGE_ELEVENTY.tsEntry);
-    }
-
-    fs.writeFileSync(eleventyPath, content);
-}
-
 // ── UI ────────────────────────────────────────────────────────────────────────
 
 function askChoice(question, choices) {
@@ -527,7 +505,6 @@ async function init() {
     }
 
     applyFramework(framework);
-    applyLanguage(language);
 
     installDependencies(backend);
 

package/docs/Components.md

@@ -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>
 
-```njk
+```js
 ---
 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
-```njk
+```html
 <section class="hero">
   {% include "hero/hero-title.njk" %}
   {% include "hero/hero-button.njk" %}
@@ -58,6 +58,85 @@ A component can include other components. This is useful for breaking complex se
 
 > The same path rules apply: if the included component is in a subfolder, specify the full relative path.
 
+## Markdown files
+
+### What is Markdown
+
+Markdown (`.md`) is a way to write formatted text without HTML tags. You write
+`**bold**` instead of `<strong>bold</strong>`, and a line starting with `-`
+becomes a list item. For a page that is mostly text — an article, a privacy
+policy, a changelog — it is much faster than writing the markup by hand.
+
+### Write the file
+
+Create a `.md` file in `src/frontend/components/`, next to your `.njk` ones.
+
+#### article.md <small>(`src/frontend/components/`)</small>
+
+```markdown
+## Section title
+
+Regular paragraph text. **Bold** and *italic* work as usual.
+
+- First item
+- Second item
+```
+
+### Show it in a page
+
+Open the page's file in `src/frontend/routes/` and add this line to its body:
+
+```html
+<article class="markdown-body">
+    {% renderFile "article.md" | markdownPath, { site: site } %}
+</article>
+```
+
+Four parts to it:
+
+| Part | What it does |
+|---|---|
+| `class="markdown-body"` | the wrapper that applies the Markdown styling — without it your content renders unstyled |
+| `renderFile` | turns the Markdown into HTML and puts it in the page |
+| `markdownPath` | fills in the `src/frontend/components/` part of the path for you |
+| `{ site: site }` | hands the file your site settings — see below |
+
+Subfolders work the same way as with components:
+`"legal/privacy.md" | markdownPath`
+
+### Why `{ site: site }`
+
+A `.md` file can use site values, exactly like a component:
+
+```markdown
+Welcome to {{ site.title }}
+```
+
+But a Markdown file does not automatically see them. Anything the file needs has
+to be listed in the curly braces:
+
+```js
+{% renderFile "article.md" | markdownPath, { site: site, pages: pages } %}
+```
+
+If you forget, nothing breaks — the value simply comes out empty. So if a
+`{{ site.something }}` disappears from your page, this is why.
+
+### Extras you get for free
+
+**Links to a section.** Every `##` and `###` heading gets an anchor, so you can
+link straight to it: `yoursite.com/my-page/#section-title`.
+
+**CSS classes.** Markdown produces plain HTML with no classes, so your framework's
+styling doesn't reach it. Add a class in curly braces after the element:
+
+```markdown
+## Section title {.text-center}
+```
+
+> ⚠️ If the `.md` file is missing or the name is misspelled, the build stops with
+> an error. That is on purpose: silently skipping content you asked for is worse.
+
 ## Global components
 
 Header and footer live in `src/frontend/components/global/` and are automatically included in every page via `base.njk`. Edit them to change the site-wide layout
@@ -84,7 +163,7 @@ src/frontend/layouts/
 
 Same as `base.njk`, without the two global includes:
 
-```njk
+```html
 <body>
     <main>
         {{ content | safe }}
@@ -96,7 +175,7 @@ Then point the route at it:
 
 ### landing.njk <small>(`src/frontend/routes/`)</small>
 
-```njk
+```js
 ---
 title: "landing"
 permalink: "/landing/"
@@ -142,55 +221,17 @@ All values defined in `src/frontend/data/site.json` are globally available in ev
 `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
-```njk
+```html
 <p>{{ site.title }}</p>
 <a href="{{ site.legal.privacy }}">Privacy Policy</a>
 <img src="{{ site.logo }}" alt="{{ site.title }}">
 ```
 
+> In a `.md` file rendered with `renderFile`, these values only work if you passed
+> `site` in the curly braces — see *Why `{ site: site }`* above.
+
 ## Your own data files
 
 `site.json` isn't special: **any** `.json` file you drop in `src/frontend/data/` becomes a global variable, and the variable takes the name of the file.
 
-Create `test.json`, put anything you want inside it, and every key is reachable as `test.yourKey` — no import, no configuration, no restart.
-
-### test.json <small>(`src/frontend/data/`)</small>
-```json
-{
-  "testMessage": "This is a test"
-}
-```
-
-### Usage in any `.njk` file
-```njk
-<p>{{ test.testMessage }}</p>
-```
-
-Renders as:
-```html
-<p>This is a test</p>
-```
-
-That's the whole rule: **file name = variable name, keys inside = what you write after the dot.** `site.json` gives you `site.title` for exactly the same reason.
-
-Values can be anything JSON allows, so a list lets you loop instead of copying markup:
-
-```json
-{
-  "testMessage": "This is a test",
-  "links": [
-    { "label": "Home",    "url": "/" },
-    { "label": "Contact", "url": "/contact/" }
-  ]
-}
-```
-
-```njk
-{% for link in test.links %}
-  <a href="{{ link.url }}">{{ link.label }}</a>
-{% endfor %}
-```
-
-Subfolders create nested names: `data/shop/products.json` becomes `{{ shop.products }}`.
-
-> ⚠️ Don't reuse a name that already exists. Another file named `site.json` in a subfolder overwrites the original one silently, with no error to point you at the cause.
+Create `test.json`, put anything you want inside it, and every key is reachable as `test.yourKey` — no import, no configuration, no restart.

package/docs/Creating pages.md

@@ -17,7 +17,9 @@ It also adds a stub entry in `src/frontend/data/pages.json` for the page's SEO a
 
 ## Adding content
 
-The route is created empty. Write your HTML in its body, or include components — see the **Components** DOC file.
+The route is created empty, with two commented examples: one for including a
+`.njk` component, one for rendering a `.md` file. Uncomment the one you need or
+write your HTML directly in the body — see the **Components** DOC file.
 
 ## URL and title
 
@@ -33,7 +35,7 @@ A page that needs a different shell — a landing page with no header, for insta
 
 To create a URL like `domain.it/about/team`, edit the `permalink` in `src/frontend/routes/team.njk` and add the parent segment before the final slash:
 
-```njk
+```js
 ---
 title: "team"
 permalink: "/about/team/"