@slybridges/kiss 0.6.6 → 0.8.0

package/.eslintrc.js

@@ -3,7 +3,7 @@ module.exports = {
     es6: true,
     node: true,
   },
-  extends: "eslint:recommended",
+  extends: ["eslint:recommended", "prettier"],
   parserOptions: {
     ecmaVersion: 12,
   },

package/README.md

@@ -42,7 +42,7 @@ Concept is being tuned until reaching v1. Things might break. Use at your own ri
 
 ## Requirements
 
-Node 12 or above.
+Node 20 or above.
 
 ## Quick start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slybridges/kiss",
-  "version": "0.6.6",
+  "version": "0.8.0",
   "description": "Keep It Simple and Static site generator",
   "main": "src/index.js",
   "bin": {
@@ -12,24 +12,26 @@
   "author": "Sylvestre Dupont",
   "license": "MIT",
   "dependencies": {
-    "browser-sync": "^2.29.3",
+    "browser-sync": "^3.0.2",
     "chalk": "^4.1.2",
     "cheerio": "^1.0.0-rc.12",
-    "chokidar": "^3.5.3",
-    "date-fns": "^2.30.0",
-    "fast-glob": "^3.3.1",
+    "chokidar": "^3.6.0",
+    "date-fns": "^3.6.0",
+    "fast-glob": "^3.3.2",
     "front-matter": "^4.0.2",
-    "fs-extra": "^11.1.1",
+    "fs-extra": "^11.2.0",
     "lodash": "^4.17.21",
-    "marked": "^8.0.1",
+    "marked": "^12.0.1",
     "nunjucks": "^3.2.4",
-    "sharp": "^0.32.5",
+    "sharp": "^0.33.3",
     "slugify": "^1.6.6",
     "xml": "^1.0.1",
     "yargs": "^17.7.2"
   },
   "devDependencies": {
-    "eslint": "^8.49.0"
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.2.5"
   },
   "repository": {
     "type": "git",

package/src/build.js

@@ -5,14 +5,14 @@ const fg = require("fast-glob")
 const path = require("path")
 
 const { loadConfig } = require("./config")
-const { getParentId } = require("./helpers")
+const { getParentId, relativeToAbsoluteAttributes } = require("./helpers")
 const { baseLoader } = require("./loaders")
 const { setGlobalLogger } = require("./logger")
 
 const build = async (options = {}, config = null) => {
   console.time("Build time")
 
-  const { configFile, verbosity, watchMode } = options
+  const { configFile, unsafeBuild, verbosity, watchMode } = options
 
   setGlobalLogger(verbosity)
 
@@ -37,7 +37,7 @@ const build = async (options = {}, config = null) => {
   }
 
   global.logger.section(
-    `Loading content from '${config.dirs.content}' directory`
+    `Loading content from '${config.dirs.content}' directory`,
   )
   context.pages = await loadContent(config, context)
 
@@ -68,12 +68,18 @@ const build = async (options = {}, config = null) => {
   const warningCount = global.logger.counts.warn
   if (errorCount > 0) {
     global.logger.error(
-      `${errorCount} error(s) and ${warningCount} warning(s) found.`
+      `${errorCount} error(s) and ${warningCount} warning(s) found.`,
     )
     if (!watchMode) {
-      console.timeEnd("Build time")
-      global.logger.info("Exiting build with errors.")
-      process.exit(1)
+      if (unsafeBuild) {
+        global.logger.info(
+          "Unsafe build mode: exiting build with errors without raising exit(1)",
+        )
+      } else {
+        global.logger.info("Exiting build with errors.")
+        console.timeEnd("Build time")
+        process.exit(1)
+      }
     }
   } else if (warningCount > 0) {
     global.logger.warn(`${warningCount} warning(s) found.`)
@@ -95,7 +101,7 @@ const applyTransforms = async (context, config) => {
   const validScopes = [null, "PAGE", "CONTEXT"]
   for await (let transform of config.transforms) {
     const { scope, handler, outputType, namespace, ...rest } = transform
-    const options = namespace ? _.get(config, namespace, {}) : rest
+    const options = getOptions(config, namespace, rest)
     if ("active" in options && !options.active) {
       global.logger.log(`- [${handler.name}]: transform not active. Skipping.`)
       continue
@@ -104,7 +110,7 @@ const applyTransforms = async (context, config) => {
       throw new Error(
         `[applyTransforms]: invalid scope for transform ${
           handler.name
-        }, got '${scope}'. Valid choices are ${JSON.stringify(validScopes)}`
+        }, got '${scope}'. Valid choices are ${JSON.stringify(validScopes)}`,
       )
     }
     if (scope === "CONTEXT") {
@@ -117,7 +123,7 @@ const applyTransforms = async (context, config) => {
       } catch (err) {
         global.logger.error(
           `[${handler.name}] Error during transform:\n`,
-          err.stack
+          err.stack,
         )
       }
     } else {
@@ -136,7 +142,7 @@ const applyTransforms = async (context, config) => {
         } catch (err) {
           global.logger.error(
             `[${handler.name}] Error during transform of page '${id}'\n`,
-            err.stack
+            err.stack,
           )
         }
       }
@@ -157,7 +163,7 @@ const computeDataViews = (context, config) => {
     } catch (err) {
       global.logger.error(
         `[${handler.name}] Error during computing data view for '${attribute}'\n`,
-        err.stack
+        err.stack,
       )
     }
   })
@@ -197,7 +203,7 @@ const computePageData = (data, config, context, options = {}) => {
         currentPending = countPendingDependencies(
           options.topLevelData,
           context.pages,
-          value.kissDependencies
+          value.kissDependencies,
         )
       }
       if (currentPending == 0) {
@@ -236,7 +242,7 @@ const computeAllPagesData = (context, config) => {
       } catch (err) {
         global.logger.error(
           `[computePageData] Error during computing page data for page id '${page._meta.id}'\n`,
-          err.stack
+          err.stack,
         )
       }
       context.pages[key] = computed.data
@@ -245,13 +251,13 @@ const computeAllPagesData = (context, config) => {
     if (pendingTotal > 0 && round + 1 > config.defaults.maxComputingRounds) {
       global.logger.error(
         ```Could not compute all data in ${config.defaults.maxComputingRounds} rounds. Check for circular
-dependencies or increase the 'maxComputingRounds' value.```
+dependencies or increase the 'maxComputingRounds' value.```,
       )
       break
     }
     if (pendingTotal > 0) {
       global.logger.log(
-        `- Round ${round}: ${pendingTotal} data points could not yet be computed. New round.`
+        `- Round ${round}: ${pendingTotal} data points could not yet be computed. New round.`,
       )
     } else {
       global.logger.log(`- Round ${round}: all data points computed.`)
@@ -282,8 +288,8 @@ const countPendingDependencies = (page, pages, deps = []) => {
             (pendingCount += countPendingDependencies(
               pages[id],
               pages,
-              restDeps
-            ))
+              restDeps,
+            )),
         )
       } else if (isComputableValue(depValue)) {
         pendingCount++
@@ -293,7 +299,7 @@ const countPendingDependencies = (page, pages, deps = []) => {
       }
     } else {
       throw new Error(
-        `countPendingDependencies: dependency should either be a string or an array of strings: ${dep}`
+        `countPendingDependencies: dependency should either be a string or an array of strings: ${dep}`,
       )
     }
   })
@@ -321,7 +327,7 @@ const directoryCollectionLoader = (pathname, options, pages, config) => {
     { isDirectory: true, collectionGroup: "directory" },
     isTopLevel ? config.defaults.pageData : {},
     pages,
-    config
+    config,
   )
 
   return _.merge({}, pages, {
@@ -333,72 +339,92 @@ const isComputableValue = (value) =>
   typeof value === "function" ||
   (_.isPlainObject(value) && value._kissCheckDependencies)
 
+const getOptions = (config, namespace, options) => {
+  const nameSpaceOptions = _.get(config, namespace, {})
+  return { ...nameSpaceOptions, ...options }
+}
+
 const loadContent = async (config, context) => {
   let pages = {}
-  // file loaders
-  await Promise.all(
-    config.loaders
-      .filter((loader) => !loader.source || loader.source === "file")
-      .map(async ({ handler, namespace, ...loaderOptions }) => {
-        const {
-          description,
-          match,
-          matchOptions = {},
-          ...options
-        } = namespace ? _.get(config, namespace, {}) : loaderOptions
-        if ("active" in options && !options.active) {
-          global.logger.log(`- [${handler.name}]: loader not active. Skipping.`)
-          return
-        }
-        let fgOptions = {
-          cwd: config.dirs.content,
-          markDirectories: true,
-          stats: true,
-          ...matchOptions,
-        }
-        const message =
-          description ||
-          `Loading files matching ${JSON.stringify(match)} using ${
-            handler.name
-          }`
-        global.logger.info(message)
-        let files = fg.sync(match, fgOptions)
-        // sort files to make sure index files are loaded first
-        // and respect the data cascade principle
-        files = sortIndexFirst(files)
-        for (const file of files) {
-          let pathname = path.join(config.dirs.content, file.path)
-          let page = {}
-          try {
-            // load parent folders, if any
-            pages = directoryCollectionLoader(pathname, options, pages, config)
-            // load stats
-            page = {
-              _meta: {
-                fileCreated: file.stats.ctime,
-                fileModified: file.stats.mtime,
-              },
-            }
-            // load base data including _meta infos and based on ParentData
-            page = baseLoader(pathname, options, page, pages, config)
-            // load content specific data
-            page = handler(pathname, options, page, context, config)
-            pages[page._meta.id] = page
-            global.logger.log(
-              `- [${handler.name}] loaded '${page._meta.inputPath}'`
-            )
-          } catch (err) {
-            global.logger.error(
-              `- [${handler.name}] Error loading '${_.get(
-                page,
-                "_meta.inputPath"
-              )}'\n`,
-              err.stack
-            )
-          }
-        }
-      })
+  let files = []
+  // We first need to fetch all files that match all loaders
+  // So that we can sort them in the right order before loading them
+  // This is essential for the data cascade to work properly
+  config.loaders.forEach(
+    ({ handler, namespace, source, ...loaderOptions }, idx) => {
+      if (source && source !== "file") {
+        return
+      }
+      const allOptions = getOptions(config, namespace, loaderOptions)
+      const { match, matchOptions = {}, ...options } = allOptions
+      if ("active" in options && !options.active) {
+        global.logger.log(`[${handler.name}]: loader not active. Skipping.`)
+        return
+      }
+      let fgOptions = {
+        cwd: config.dirs.content,
+        markDirectories: true,
+        stats: true,
+        ...matchOptions,
+      }
+      let extraOptions = []
+      if (namespace !== handler.name) {
+        extraOptions.push(`namespace: '${namespace}'`)
+      }
+      if (loaderOptions && Object.keys(loaderOptions).length > 0) {
+        extraOptions.push(`options: ${JSON.stringify(loaderOptions)}`)
+      }
+      global.logger.info(
+        `Listing files matching ${JSON.stringify(match)} for ${handler.name}${extraOptions.length > 0 ? ` (${extraOptions.join(", ")})` : ""}`,
+      )
+      files = files.concat(
+        fg.sync(match, fgOptions).map((file) => ({ ...file, loaderIdx: idx })),
+      )
+    },
+  )
+  global.logger.info(
+    `Found ${files.length} files. Sorting them for the data cascade.`,
   )
+  // sorting and loading files
+  // sort files to make sure index.* files are loaded first and post.* files last
+  // in order to respect the data cascade principle
+  files = sortFiles(files)
+  global.logger.info(`Loading files...`)
+  for (const file of files) {
+    // finding the right loader for the file
+    const { handler, namespace, ...loaderOptions } =
+      config.loaders[file.loaderIdx]
+    const options = getOptions(config, namespace, loaderOptions)
+    let pathname = path.join(config.dirs.content, file.path)
+    let page = {}
+    try {
+      // load parent folders, if any
+      pages = directoryCollectionLoader(pathname, options, pages, config)
+      // load stats
+      page = {
+        _meta: {
+          fileCreated: file.stats.ctime,
+          fileModified: file.stats.mtime,
+        },
+      }
+      // load base data including _meta infos and based on ParentData
+      page = baseLoader(pathname, options, page, pages, config)
+      // load content specific data
+      page = await handler(pathname, options, page, context, config)
+      // relative @attributes to absolute
+      page = relativeToAbsoluteAttributes(page, options, config)
+      pages[page._meta.id] = page
+      global.logger.log(`- [${handler.name}] loaded '${page._meta.inputPath}'`)
+    } catch (err) {
+      global.logger.error(
+        `- [${handler.name}] Error loading '${_.get(
+          page,
+          "_meta.inputPath",
+        )}'\n`,
+        err.stack,
+      )
+    }
+  }
   // computed loaders
   _.filter(config.loaders, (loader) => loader.source === "computed").forEach(
     (loader) => {
@@ -407,7 +433,7 @@ const loadContent = async (config, context) => {
         description || `Loading computed pages using ${handler.name}`
       global.logger.info(message)
       pages = handler(pages, options, config)
-    }
+    },
   )
   return pages
 }
@@ -452,7 +478,7 @@ const runCopyHook = ({ from, to, description }, config) => {
   } catch (e) {
     global.logger.error(
       `Error copying from '${from}' to '${publicTo}'\n`,
-      e.stack
+      e.stack,
     )
   }
 }
@@ -468,16 +494,39 @@ const runExecHook = (command, options) => {
   }
 }
 
-const sortIndexFirst = (files) => {
+// Sort files using those rules:
+// Files higher in the list will be loaded first
+// Inside the same directory load index first, all other files but post files after and post files last
+const sortFiles = (files) => {
   return files.sort((fileA, fileB) => {
     const isAIndexFile = fileA.name.startsWith("index.")
     const isBIndexFile = fileB.name.startsWith("index.")
+    const isAPostFile = fileA.name.startsWith("post.")
+    const isBPostFile = fileB.name.startsWith("post.")
+
     if (isAIndexFile && isBIndexFile) {
       // both are indexes
       // return the shortest path first to respect data cascade
-      return fileB.path.length < fileA.path.length ? 1 : -1
+      return fileA.path.length < fileB.path.length ? -1 : 1
+    }
+    if (isAIndexFile || isBIndexFile) {
+      // one of them is an index file
+      // index files first
+      return isAIndexFile ? -1 : 1
+    }
+    if (isAPostFile && isBPostFile) {
+      // both are post files
+      // we don't want higher up post files to impact lower post files
+      // so we return the longest path first
+      return fileA.path.length < fileB.path.length ? 1 : -1
     }
-    return isBIndexFile && !isAIndexFile ? 1 : -1
+    if (isAPostFile || isBPostFile) {
+      // one of them is a post file
+      // post files last
+      return isAPostFile ? 1 : -1
+    }
+    // all other files
+    return 0
   })
 }
 
@@ -493,38 +542,42 @@ const runHandlerHook = (handler, options, config, data) => {
 }
 
 const writeStaticSite = async (context, config) => {
-  global.logger.info("Writing individual pages")
+  global.logger.info("Writing individual pages and images")
   await Promise.all(
     _.map(context.pages, async (page) => {
-      if (!page.permalink) {
+      if (page.excludeFromWrite) {
+        global.logger.log(
+          `- Page '${page._meta.id}' is marked as excludeFromWrite. Skipping.`,
+        )
+      } else if (!page.permalink) {
         global.logger.log(
-          `- Page '${page._meta.id}' has no permalink. Skipping.`
+          `- Page '${page._meta.id}' has no permalink. Skipping.`,
         )
       } else {
         const writer = config.writers.find(
-          (writer) => writer.outputType === page._meta.outputType
+          (writer) => writer.outputType === page._meta.outputType,
         )
         if (writer) {
           const { handler, namespace, ...rest } = writer
-          const options = namespace ? _.get(config, namespace, {}) : rest
+          const options = getOptions(config, namespace, rest)
           try {
             await handler(page, options, config, context)
             global.logger.log(
-              `- [${writer.handler.name}] wrote '${page._meta.outputPath}'`
+              `- [${writer.handler.name}] wrote '${page._meta.outputPath}'`,
             )
           } catch (err) {
             global.logger.error(
               `- [${writer.handler.name}] error writing '${page._meta.outputPath}'\n`,
-              err.stack
+              err.stack,
             )
           }
         } else {
           global.logger.warn(
-            `- no writer for type '${page._meta.outputType}' found for '${page._meta.inputPath}'. Skipping.`
+            `- no writer for type '${page._meta.outputType}' found for '${page._meta.inputPath}'. Skipping.`,
           )
         }
       }
-    })
+    }),
   )
   const contextWriters = _.filter(config.writers, { scope: "CONTEXT" })
   if (contextWriters.length === 0) {
@@ -534,7 +587,7 @@ const writeStaticSite = async (context, config) => {
   return await Promise.all(
     contextWriters.map(async (writer) => {
       const { handler, namespace, ...rest } = writer
-      const options = namespace ? _.get(config, namespace, {}) : rest
+      const options = getOptions(config, namespace, rest)
       if ("active" in options && !options.active) {
         global.logger.log(`- [${handler.name}]: writer not active. Skipping.`)
         return
@@ -542,14 +595,14 @@ const writeStaticSite = async (context, config) => {
       try {
         await handler(context, options, config)
         global.logger.log(
-          `- [${handler.name}] wrote ${options.target || "file"}`
+          `- [${handler.name}] wrote ${options.target || "file"}`,
         )
       } catch (err) {
         global.logger.error(
           `- [${handler.name}] error writing ${options.target || "file"}\n`,
-          err.stack
+          err.stack,
         )
       }
-    })
+    }),
   )
 }

package/src/cli.js

@@ -11,7 +11,7 @@ yargs(hideBin(process.argv))
     "start",
     "start server and rebuilds on changes (serve + watch)",
     () => {},
-    start
+    start,
   )
   .command("serve", "start development server", () => {}, serve)
   .command("watch", "watch files and rebuild site on changes", () => {}, watch)
@@ -21,4 +21,10 @@ yargs(hideBin(process.argv))
     describe: "Verbosity level",
     choices: ["log", "info", "success", "warn", "error"],
   })
+  .option("u", {
+    alias: "unsafe-build",
+    boolean: true,
+    default: false,
+    describe: "Won't exit(1) on build errors",
+  })
   .demandCommand(1, "Enter a command").argv

package/src/config/defaultConfig.js

@@ -14,6 +14,7 @@ const {
   textLoader,
 } = require("../loaders")
 const {
+  atAttributesContentTransform,
   imageContextTransform,
   nunjucksContentTransform,
 } = require("../transforms")
@@ -69,16 +70,21 @@ const defaultConfig = {
   defaults: {
     sortCollectionBy: "-created",
     dateFormat: "MMMM do, yyyy 'at' hh:mm aaa",
+    // descriptionLength: how many characters to use for the description field
+    // Meta descriptions can be any length, but Google generally truncates snippets to ~155–160 characters.
+    // https://moz.com/learn/seo/meta-description
+    // This settings only applies to description automatically generated. If you provide your own description, it will be used as is.
+    descriptionLength: 160,
     maxComputingRounds: 10,
     pageData: initialPageData,
     pagePublishedAttribute: "created",
     pageUpdatedAttribute: "modified",
   },
   dirs: {
-    content: "content",
-    public: "public",
-    theme: "theme",
-    template: "theme/templates",
+    content: "content", // where to load documents from
+    public: "public", // where to write the generated files
+    theme: "theme", // where to find templates and other design files
+    template: "theme/templates", // where to find templates
     watchExtra: [], // additional paths to watch for change in watch mode
   },
   env: env,
@@ -114,9 +120,11 @@ const defaultConfig = {
   loaders: [
     { handler: jsLoader, namespace: "jsLoader" },
     { handler: jsonLoader, namespace: "jsonLoader" },
-    { handler: markdownLoader, namespace: "markdownLoader" },
     { handler: staticLoader, namespace: "staticLoader" },
     { handler: textLoader, namespace: "textLoader" },
+    // image is loaded in a separate staticLoader to allow for image optimization later
+    { handler: staticLoader, namespace: "image", outputType: "IMAGE" },
+    { handler: markdownLoader, namespace: "markdownLoader" },
     // Use the example below to create computed tag pages from the "tags" attribute found in pages
     // {
     //   source: "computed",
@@ -131,10 +139,16 @@ const defaultConfig = {
       handler: nunjucksContentTransform,
       description: "Applying Nunjucks templates to content",
     },
+    {
+      outputType: "HTML",
+      handler: atAttributesContentTransform,
+      description: "Finding and resolving @attributes",
+    },
     {
       scope: "CONTEXT",
       namespace: "image",
       handler: imageContextTransform,
+      description: "Finding and preparing images to optimize",
     },
   ],
   writers: [
@@ -160,22 +174,33 @@ const defaultConfig = {
     blur: false, // turning to true requires https://github.com/verlok/vanilla-lazyload
     blurWidth: 32,
     defaultWidth: 1024,
-    description: "Optimizing images",
     filename: defaultImageFilename,
-    formats: ["jpeg"], // webp, avif
+    // output format of images
+    formats: ["original"],
+    // input path and format of images
+    match: ["**/*.jpg", "**/*.jpeg", "**/*.png", "**/*.webp"],
     overwrite: env === "production", // if false, won't regenerate the image if already in public dir
     sizes: ["(min-width: 1024px) 1024px", "100vw"],
     widths: [320, 640, 1024, 1366, "original"],
+    // defaultFormat: "jpeg", // if not present, will use formats[0]
     // resizeOptions: { /*... any option accepted by sharp.resize()*/ }
     // jpegOptions: { /*... any option accepted by sharp.jpeg()*/ }
     // webpOptions: { /*... any option accepted by sharp.webp()*/ }
     // avifOptions: { /*... any option accepted by sharp.avif()*/ }
   },
+  templates: {
+    collection: "collection.njk",
+    default: "default.njk",
+    post: "post.njk",
+  },
   rss: {
     active: true,
     target: "feed.xml",
     pageFilter: (page) =>
-      page.url && page._meta.isPost && !page.excludeFromCollection,
+      page.url &&
+      page._meta.isPost &&
+      !page.excludeFromWrite &&
+      !page.excludeFromSitemap,
     xmlOptions: {
       declaration: true,
       indent: env === "production" ? null : "  ",
@@ -200,7 +225,11 @@ const defaultConfig = {
       collection: 0.5,
     },
     target: "sitemap.xml",
-    pageFilter: (page) => page.url && page._meta.outputType === "HTML",
+    pageFilter: (page) =>
+      page.url &&
+      page._meta.outputType === "HTML" &&
+      !page.excludeFromWrite &&
+      !page.excludeFromSitemap,
     xmlOptions: {
       declaration: true,
       indent: env === "production" ? null : "  ",
@@ -216,7 +245,7 @@ module.exports = defaultConfig
 function addPlugin(pluginFunc, options) {
   if (typeof pluginFunc !== "function") {
     throw new Error(
-      `config.addPlugin(): plugin argument should be a function, got: '${typeof pluginFunc}'`
+      `config.addPlugin(): plugin argument should be a function, got: '${typeof pluginFunc}'`,
     )
   }
   global.logger.info(`Loading '${pluginFunc.name}' plugin`)

package/src/config/loadConfig.js

@@ -32,17 +32,17 @@ const checkConfig = (config) => {
   const siteURL = _.get(config, "context.site.url")
   if (!isValidURL(siteURL)) {
     global.logger.error(
-      `[checkConfig] 'context.site.url' is required and should be a valid URL (e.g. https://example.org), got ${siteURL}.`
+      `[checkConfig] 'context.site.url' is required and should be a valid URL (e.g. https://example.org), got ${siteURL}.`,
     )
   }
   if (!_.get(config, "context.site.title")) {
     global.logger.warn(
-      `[checkConfig] No site title found. We highly recommend to set it in 'context.site.title'.`
+      `[checkConfig] No site title found. We highly recommend to set it in 'context.site.title'.`,
     )
   }
   if (!_.get(config, "context.site.image")) {
     global.logger.warn(
-      `[checkConfig] No default image found. We highly recommend to set one in  'context.site.image'.`
+      `[checkConfig] No default image found. We highly recommend to set one in  'context.site.image'.`,
     )
   }
 }