nibula 2.0.2 → 2.1.0

package/docs/Project structure.md

@@ -17,7 +17,7 @@ your-project/
     └── frontend/
         ├── assets/       # Images, fonts, brand files
         │   └── brand/    # Favicons, logo etc
-        ├── components/   # Reusable .njk fragments
+        ├── components/   # Reusable .njk fragments and .md content
         │   └── global/   # Header and footer, included in every page
         ├── data/         # site.json and pages.json
         ├── hosting/      # .htaccess and web.config
@@ -35,6 +35,7 @@ your-project/
 | Add a page | `nib cli` → creates the files in `routes/`, `scss/pages/`, `js/pages/` |
 | Write the content of a page | `routes/` |
 | Build a reusable block of markup | `components/` |
+| Write long prose in Markdown | `components/` — see docs/Components.md |
 | Change the header or footer | `components/global/` |
 | Style one page | `scss/pages/` |
 | Style every page | `scss/_global.scss` |
@@ -57,7 +58,7 @@ your-project/
 
 Subfolders are allowed wherever content is yours to organize:
 
-- `components/` — nest as deep as you like; includes take the path relative to `components/`
+- `components/` — nest as deep as you like; includes take the path relative to `components/`, and so does the `markdownPath` filter
 - `scss/modules/` and `js/modules/` — same idea, remember to update the relative import paths
 - `layouts/` — extra layouts alongside `base.njk`; routes pick one by filename
 - `backend/api/public/` and `protected/` — subfolders become part of the URL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nibula",
-  "version": "2.0.2",
+  "version": "2.1.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",
@@ -63,6 +63,8 @@
     "esbuild": "^0.27.3",
     "foundation-sites": "^6.9.0",
     "glob": "^13.0.6",
+    "markdown-it-anchor": "^9.2.1",
+    "markdown-it-attrs": "^5.0.1",
     "sass": "^1.77.0",
     "uikit": "^3.25.13"
   }

package/src/frontend/layouts/base.njk

@@ -1,4 +1,4 @@
-<!-- This is the base of every page that you will create -->
+{# This is the base of every page that you will create #}
 
 <!DOCTYPE html>
 <html lang="{{ site.lang or 'en' }}" data-theme="{{ site.theme or 'light' }}" data-bs-theme="{{ site.theme or 'light' }}">

package/src/frontend/routes/404.njk

@@ -4,7 +4,8 @@ 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-->
+{# To keep order, create a new component in components/ and include it here #}
+{% include "not-found.njk" ignore missing %}
 
-{% include "not-found.njk" ignore missing %}
+{# Markdown files live in components/ too. Pass the data the file needs #}
+{# {% renderFile "example.md" | markdownPath, { site: site } %} #}

package/src/frontend/routes/index.njk

@@ -4,7 +4,8 @@ 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-->
+{# To keep order, create a new component in components/ and include it here #}
+{% include "welcome.njk" ignore missing %}
 
-{% include "welcome.njk" ignore missing %}
+{# Markdown files live in components/ too. Pass the data the file needs #}
+{# {% renderFile "example.md" | markdownPath, { site: site } %} #}

package/tools/assistant.js

@@ -5,11 +5,13 @@ const { validatePageName, validateOutputPath, checkRequiredFiles } = require('./
 const { addPage, removePage, renamePage } = require('./lib/pageActions');
 const { pageExists } = require('./lib/pageArtifacts');
 const { updateOutputPath, getCurrentOutputPath } = require('./lib/outputPath');
-const { ask, confirm, close } = require('./cli/prompt');
+const { availableLayouts } = require('./lib/layouts');
+const { ask, confirm, askChoice, close } = require('./cli/prompt');
 const ui = require('./cli/ui');
 
 const NEW_LINE = '\n';
 const NO_PREFIX = '';
+const NO_LAYOUT = '';
 
 async function askPageName(prompt) {
     const raw = await ask(prompt);
@@ -24,9 +26,26 @@ async function askPageName(prompt) {
     return name;
 }
 
+async function askLayout() {
+    const layouts = availableLayouts();
+    if (layouts.length === 0) return NO_LAYOUT;
+    if (layouts.length === 1) return layouts[0];
+
+    const choices = layouts.map((name) => ({ label: name, value: name }));
+    return askChoice(message('cli.layoutPrompt'), choices);
+}
+
 async function handleCreate() {
     const name = await askPageName(ui.promptLine(message('cli.createPrompt')));
-    if (name) addPage(name);
+    if (!name) return;
+
+    const layoutName = await askLayout();
+    if (layoutName === null) {
+        ui.notice(message('cli.cancelled'));
+        return;
+    }
+
+    addPage(name, layoutName);
 }
 
 async function handleRemove() {

package/tools/cli/prompt.js

@@ -1,30 +1,58 @@
 const readline = require('readline');
 const settings = require('../config/settings.json');
-const { color } = require('../lib/colors');
+const { color, paint } = require('../lib/colors');
 
 const CONTROL_CHARACTERS_PATTERN = /[\x00-\x1F\x7F]/g;
 const AFFIRMATIVE_PATTERN = /^y(es)?$/i;
 const CONFIRM_HINT = settings.cli.confirmHint;
 const EMPTY = '';
+const NEW_LINE = '\n';
 
-const readlineInterface = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-    terminal: true,
-});
+const CURSOR_UP_PREFIX = '\x1B[';
+const CURSOR_UP_SUFFIX = 'A';
+const CLEAR_LINE = '\x1B[K';
+const CHOICE_INDENT = '  ';
+
+const SELECTED_SYMBOL = settings.cli.symbols.selected;
+const UNSELECTED_SYMBOL = settings.cli.symbols.unselected;
+const SELECTED_COLOR = settings.cli.colors.selected;
+
+const EXIT_KEYS = ['c', 'd'];
+const UP_KEY = 'up';
+const DOWN_KEY = 'down';
+const CONFIRM_KEYS = ['return', 'enter'];
+
+let activeInterface = null;
 
 function sanitizeInput(value) {
     return (value ?? EMPTY).replace(CONTROL_CHARACTERS_PATTERN, EMPTY).trim();
 }
 
+function cursorUp(lines) {
+    return `${CURSOR_UP_PREFIX}${lines}${CURSOR_UP_SUFFIX}`;
+}
+
 function ask(prompt) {
     return new Promise((resolve) => {
-        const onClose = () => resolve(null);
-        readlineInterface.once('close', onClose);
-        readlineInterface.question(prompt, (answer) => {
-            readlineInterface.off('close', onClose);
-            resolve(sanitizeInput(answer));
+        const readlineInterface = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: true,
         });
+
+        activeInterface = readlineInterface;
+        let settled = false;
+
+        const finish = (value) => {
+            if (settled) return;
+            settled = true;
+            activeInterface = null;
+            readlineInterface.close();
+            resolve(value);
+        };
+
+        readlineInterface.on('close', () => finish(null));
+        readlineInterface.question(prompt, (answer) => finish(sanitizeInput(answer)));
     });
 }
 
@@ -33,8 +61,66 @@ async function confirm(prompt) {
     return AFFIRMATIVE_PATTERN.test((answer ?? EMPTY).trim());
 }
 
+function askChoice(prompt, choices) {
+    return new Promise((resolve) => {
+        let selectedIndex = 0;
+        let settled = false;
+
+        process.stdout.write(`${prompt}${NEW_LINE}${NEW_LINE}`);
+
+        const render = (firstRender) => {
+            if (!firstRender) process.stdout.write(cursorUp(choices.length));
+
+            const output = choices.map((choice, index) => {
+                const selected = index === selectedIndex;
+                const symbol = selected ? SELECTED_SYMBOL : UNSELECTED_SYMBOL;
+                const label = `${CHOICE_INDENT}${symbol} ${choice.label}`;
+                const line = selected ? paint(SELECTED_COLOR, label) : label;
+                return `${line}${CLEAR_LINE}${NEW_LINE}`;
+            }).join(EMPTY);
+
+            process.stdout.write(output);
+        };
+
+        const finish = (value) => {
+            if (settled) return;
+            settled = true;
+            process.stdin.removeListener('keypress', onKeyPress);
+            if (process.stdin.isTTY) process.stdin.setRawMode(false);
+            process.stdin.pause();
+            resolve(value);
+        };
+
+        function onKeyPress(character, key) {
+            if (key.ctrl && EXIT_KEYS.includes(key.name)) {
+                finish(null);
+                return;
+            }
+            if (key.name === UP_KEY) {
+                selectedIndex = selectedIndex > 0 ? selectedIndex - 1 : choices.length - 1;
+                render(false);
+                return;
+            }
+            if (key.name === DOWN_KEY) {
+                selectedIndex = selectedIndex < choices.length - 1 ? selectedIndex + 1 : 0;
+                render(false);
+                return;
+            }
+            if (CONFIRM_KEYS.includes(key.name)) {
+                finish(choices[selectedIndex].value);
+            }
+        }
+
+        readline.emitKeypressEvents(process.stdin);
+        if (process.stdin.isTTY) process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on('keypress', onKeyPress);
+        render(true);
+    });
+}
+
 function close() {
-    readlineInterface.close();
+    if (activeInterface) activeInterface.close();
 }
 
-module.exports = { ask, confirm, close };
+module.exports = { ask, confirm, askChoice, close };

package/tools/config/messages.json

@@ -68,6 +68,7 @@
     "renameToPrompt": "New name: ",
     "outputPathPrompt": "New output path: ",
     "menuPrompt": "Choose an option: ",
+    "layoutPrompt": "Select a layout (arrow keys, Enter to confirm):",
     "currentOutputPath": "Current path: \"{path}\"",
     "confirmRemove": "This permanently deletes all files for \"{name}\".",
     "cancelled": "Cancelled.",

package/tools/config/settings.json

@@ -13,7 +13,8 @@
     "stylePages": "src/frontend/scss/pages",
     "pagesData": "src/frontend/data/pages.json",
     "siteData": "src/frontend/data/site.json",
-    "templates": "tools/res/templates"
+    "templates": "tools/res/templates",
+    "layouts": "src/frontend/layouts"
   },
   "languages": {
     "javascript": {
@@ -69,6 +70,7 @@
     "routeExtension": "njk",
     "styleTemplate": "template.scss",
     "routeTemplate": "template.njk",
+    "layoutExtension": "njk",
     "outputFiles": [
       "js/pages/{camelName}.js",
       "css/pages/{camelName}.css",
@@ -95,7 +97,8 @@
   },
   "frontMatter": {
     "title": "title: \"{camelName}\"",
-    "permalink": "permalink: \"/{pageName}/\""
+    "permalink": "permalink: \"/{pageName}/\"",
+    "layout": "layout: {layoutName}"
   },
   "cli": {
     "title": "Nibula CLI",
@@ -105,7 +108,9 @@
       "prompt": "\u276f",
       "error": "\u2716",
       "warning": "\u26a0",
-      "bullet": "-"
+      "bullet": "-",
+      "selected": "\u25c9",
+      "unselected": "*"
     },
     "colors": {
       "box": "cyan",
@@ -113,7 +118,8 @@
       "prompt": "cyan",
       "error": "red",
       "warning": "yellow",
-      "notice": "dim"
+      "notice": "dim",
+      "selected": "cyan"
     },
     "menu": [
       { "key": "1", "action": "createPage", "label": "Create page" },

package/tools/lib/files.js

@@ -46,6 +46,10 @@ function removeFile(target) {
     return true;
 }
 
+function readDirectory(directoryPath) {
+    return fs.readdirSync(directoryPath);
+}
+
 function removeDirectory(target) {
     if (!exists(target)) return false;
     fs.rmSync(target, { recursive: true, force: true });
@@ -71,6 +75,7 @@ module.exports = {
     copyFile,
     moveFile,
     removeFile,
+    readDirectory,
     removeDirectory,
     removeDirectoryIfEmpty,
 };

package/tools/lib/layouts.js

@@ -0,0 +1,15 @@
+const settings = require('../config/settings.json');
+const { PATHS } = require('./paths');
+const { exists, readDirectory } = require('./files');
+
+const LAYOUT_SUFFIX = `.${settings.page.layoutExtension}`;
+
+function availableLayouts() {
+    if (!exists(PATHS.layouts)) return [];
+
+    return readDirectory(PATHS.layouts)
+        .filter((name) => name.endsWith(LAYOUT_SUFFIX))
+        .sort();
+}
+
+module.exports = { availableLayouts };

package/tools/lib/pageActions.js

@@ -11,13 +11,18 @@ const { readPagesData, addPageData, removePageData, renamePageData } = require('
 const FRONT_MATTER_PATTERNS = Object.freeze({
     title:     /^title:.*$/m,
     permalink: /^permalink:.*$/m,
+    layout:    /^layout:.*$/m,
 });
 
+const ROUTE_FRONT_MATTER_KEYS = ['title', 'permalink'];
+const RENAME_FRONT_MATTER_KEYS = ['permalink'];
+const LAYOUT_KEY = 'layout';
+
 function templatePath(name) {
     return path.join(PATHS.templates, name);
 }
 
-function applyFrontMatter(filePath, values, keys = Object.keys(FRONT_MATTER_PATTERNS)) {
+function applyFrontMatter(filePath, values, keys) {
     let content = readText(filePath);
 
     for (const key of keys) {
@@ -27,14 +32,17 @@ function applyFrontMatter(filePath, values, keys = Object.keys(FRONT_MATTER_PATT
     writeText(filePath, content);
 }
 
-function addPage(pageName) {
+function addPage(pageName, layoutName) {
     if (pageExists(pageName)) {
         log('page.alreadyExists', { name: pageName });
         return;
     }
 
     const { camelName, source } = getPageArtifacts(pageName);
-    const values = { camelName, pageName };
+    const values = { camelName, pageName, layoutName };
+    const frontMatterKeys = layoutName
+        ? [...ROUTE_FRONT_MATTER_KEYS, LAYOUT_KEY]
+        : ROUTE_FRONT_MATTER_KEYS;
 
     const creations = [
         { destination: source.style,  template: settings.page.styleTemplate,  isRoute: false },
@@ -52,7 +60,7 @@ function addPage(pageName) {
             }
 
             copyFile(templateFile, destination);
-            if (isRoute) applyFrontMatter(destination, values);
+            if (isRoute) applyFrontMatter(destination, values, frontMatterKeys);
 
             log('page.fileCreated', { path: destination });
         }
@@ -95,7 +103,7 @@ function renamePage(oldName, newName) {
             moveFile(source, destination);
             log('page.fileRenamed', { source, destination });
 
-            if (isRoute) applyFrontMatter(destination, values, ['permalink']);
+            if (isRoute) applyFrontMatter(destination, values, RENAME_FRONT_MATTER_KEYS);
         }
     } catch (error) {
         log('page.renameFailed', { error: error.message });

package/tools/lib/paths.js

@@ -47,6 +47,7 @@ const PATHS = Object.freeze({
     get siteData()         { return resolveFromProject(settings.paths.siteData); },
     get pagesData()        { return resolveFromProject(settings.paths.pagesData); },
     get templates()        { return resolveFromPackage(settings.paths.templates); },
+    get layouts()          { return resolveFromProject(settings.paths.layouts); },
 });
 
 function getNotInsideProjectMessage() {

package/tools/res/templates/template.njk

@@ -4,7 +4,8 @@ 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-->
+{# To keep order, create a new component in components/ and include it here #}
+{% include "component.njk" ignore missing %}
 
-{% include "component.njk" ignore missing %}
+{# Markdown files live in components/ too. Pass the data the file needs #}
+{# {% renderFile "example.md" | markdownPath, { site: site } %} #}