feat(experimental): add support for markdown in nunjucks preprocessor

Author: webdiscus

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 4.22.0-alpha.0 (2025-07-31)
+
+- feat(experimental): add support for markdown in nunjucks preprocessor
+
 ## 4.21.1 (2025-07-21)
 
 - docs: update base url of documentation pages in readme

package.json

@@ -1,6 +1,6 @@
 {
   "name": "html-bundler-webpack-plugin",
-  "version": "4.21.1",
+  "version": "4.22.0-alpha.0",
   "description": "Generates complete single-page or multi-page website from source assets. Built-in support for Markdown, Eta, EJS, Handlebars, Nunjucks, Pug. Alternative to html-webpack-plugin.",
   "keywords": [
     "html",

src/Common/FileUtils.js

@@ -92,7 +92,7 @@ const readDirRecursiveSync = (dir, { fs, includes = [], excludes = [] }) => {
  * @param {string} root The root path for the file with an absolute path (e.g., /file.html)
  * @param {Array<string>} paths Resolve a file in these paths.
  * @param {Array<string>} extensions Resolve a file without an extension with these extensions.
- * @return {string|boolean} Returns resolved file otherwise returns false.
+ * @return {string|false} Returns resolved file otherwise returns false.
  */
 const resolveFile = (file, { fs, root = process.cwd(), paths = [], extensions = [] }) => {
   const resolveFileExt = (file, extensions = []) => {
@@ -131,8 +131,12 @@ const resolveFile = (file, { fs, root = process.cwd(), paths = [], extensions =
 
   // test path/file.ext
   for (let filePath of paths) {
-    if (!filePath.endsWith(path.sep)) filePath += path.sep;
-    resolvedFile = resolveFileExt(filePath + file, extensions);
+    if (!path.isAbsolute(filePath)) {
+      filePath = path.join(root, filePath);
+    }
+
+    resolvedFile = resolveFileExt(path.join(filePath, file), extensions);
+
     if (resolvedFile) return resolvedFile;
   }
 

src/Loader/Preprocessors/Nunjucks/index.js

@@ -1,13 +1,60 @@
+const fs = require('fs');
 const path = require('path');
 const { makeTemplateId, stringifyJSON } = require('../../Utils');
-const { loadModule } = require('../../../Common/FileUtils');
+const { loadModule, resolveFile } = require('../../../Common/FileUtils');
+const MarkdownFilter = require('../../PreprocessorFilters/markdown');
+
+const markdownExtension = function (nunjucks, { viewPaths }) {
+  const name = 'includeMarkdown';
+
+  const markdownFilterOptions = {
+    highlight: {
+      use: {
+        module: 'prismjs',
+        options: {
+          verbose: true, // display loaded dependencies
+        },
+      },
+    },
+  };
+
+  function IncludeMarkdown() {
+    this.tags = [name];
+
+    this.parse = function (parser, nodes) {
+      const tok = parser.nextToken();
+      const args = parser.parseSignature(null, true);
+      parser.advanceAfterBlockEnd(tok.value);
+      return new nodes.CallExtension(this, 'run', args);
+    };
+
+    this.run = function (context, filePath) {
+      const file = resolveFile(filePath, { fs, paths: viewPaths, extensions: ['.md'] });
+
+      if (!file) {
+        throw new Error(`Could not find the include file '${filePath}'`);
+      }
+
+      const raw = fs.readFileSync(file, 'utf8');
+      const html = MarkdownFilter.getInstance(markdownFilterOptions).apply(raw);
+
+      return new nunjucks.runtime.SafeString(html);
+    };
+  }
+
+  return {
+    name,
+    extension: new IncludeMarkdown(),
+  };
+};
 
 // node module name
 const moduleName = 'nunjucks';
 
 const preprocessor = (loaderContext, options = {}, { esModule, watch }) => {
   const nunjucks = loadModule(moduleName);
-  const env = new nunjucks.Environment();
+  const { FileSystemLoader, Environment, runtime } = nunjucks;
+
   const { rootContext } = loaderContext;
   const viewPaths = (options.views = [...new Set([...(options.views || []), rootContext])]);
   const async = options?.async === true;
@@ -27,8 +74,18 @@ const preprocessor = (loaderContext, options = {}, { esModule, watch }) => {
     nunjucks.installJinjaCompat();
   }
 
-  // set root template dirs, see the options https://mozilla.github.io/nunjucks/api.html#configure
-  nunjucks.configure(viewPaths, options);
+  const env = new Environment(
+    // set root template dirs, see the options https://mozilla.github.io/nunjucks/api.html#configure
+    new FileSystemLoader(viewPaths, options),
+    options
+  );
+
+  // register custom extensions
+  const extensions = [markdownExtension(nunjucks, { viewPaths })];
+  extensions.forEach(({ name, extension }) => {
+    env.addExtension(name, extension);
+    // console.log('[nunjucks] added extension:', name);
+  });
 
   return {
     /**
@@ -48,12 +105,12 @@ const preprocessor = (loaderContext, options = {}, { esModule, watch }) => {
     render: async
       ? (content, { data }) =>
           new Promise((resolve, reject) => {
-            nunjucks.renderString(content, data, (error, result) => {
+            env.renderString(content, data, (error, result) => {
               if (!error) resolve(result);
               else reject(error);
             });
           })
-      : (source, { data = {} }) => nunjucks.renderString(source, data),
+      : (content, { data = {} }) => env.renderString(content, data),
 
     /**
      * Compile template into template function.

test/cases/_preprocessor/nunjucks-extension-markdown/expected/css/home.6a9c92dd.css

@@ -0,0 +1 @@
+h1{color:#006400}

test/cases/_preprocessor/nunjucks-extension-markdown/expected/index.html

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title></title>
+  <!-- block for specific page styles -->
+  
+  <link href="css/home.6a9c92dd.css" rel="stylesheet">
+
+  <!-- block for specific page scripts -->
+  
+  <script src="js/home.b75acc46.js" defer="defer"></script>
+
+</head>
+<body>
+  <div>header</div>
+
+  <nav>Menu > Navigation</nav>
+
+  <main class="main-content">
+    <!-- block for specific page content -->
+    
+  <h1>Hello World</h1>
+<p>This is a <strong>Markdown</strong> file rendered inside Nunjucks.</p>
+
+
+  </main>
+  <div>footer</div>
+</body>
+</html>

test/cases/_preprocessor/nunjucks-extension-markdown/expected/js/home.b75acc46.js

@@ -0,0 +1 @@
+console.log(">> home.js");

test/cases/_preprocessor/nunjucks-extension-markdown/src/views/includes/footer.html

@@ -0,0 +1 @@
+<div>footer</div>

test/cases/_preprocessor/nunjucks-extension-markdown/src/views/includes/header.html

@@ -0,0 +1 @@
+<div>header</div>

test/cases/_preprocessor/nunjucks-extension-markdown/src/views/includes/menu/nav.html

@@ -0,0 +1 @@
+<nav>Menu > Navigation</nav>