Merge pull request #55 from jverneaut/48-allow-overriding-generated-files

48 allow overriding generated files

Author: jverneaut

__tests__/parser.test.js

@@ -14,8 +14,8 @@ const UNPROCESSABLE_FIXTURES_DIR = path.join(
   "fixtures/unprocessable",
 );
 
-const getGenerateFileByType = (generateFiles, type) =>
-  generateFiles[0].files.filter((file) => file.type === type)[0].content;
+const getGenerateFileByFilename = (generateFiles, filename) =>
+  generateFiles.filter((file) => file.filename === filename)[0].content;
 
 const generateFiles = async (caseDir) => {
   const htmlToGutenberg = new HTMLToGutenberg({
@@ -25,10 +25,10 @@ const generateFiles = async (caseDir) => {
   const generatedFiles = await htmlToGutenberg.generateFiles();
 
   return {
-    index: getGenerateFileByType(generatedFiles, "index"),
-    edit: getGenerateFileByType(generatedFiles, "edit"),
-    php: getGenerateFileByType(generatedFiles, "php"),
-    json: getGenerateFileByType(generatedFiles, "json"),
+    index: getGenerateFileByFilename(generatedFiles, "index.js"),
+    edit: getGenerateFileByFilename(generatedFiles, "edit.js"),
+    php: getGenerateFileByFilename(generatedFiles, "render.php"),
+    json: getGenerateFileByFilename(generatedFiles, "block.json"),
   };
 };
 

docs/docs/advanced-guides/overriding-generated-files.mdx

@@ -0,0 +1,39 @@
+---
+sidebar_position: 1
+---
+
+# Overriding the files generated by HTML To Gutenberg
+
+By default, HTML To Gutenberg automatically generates the following files for each block found in your input directory:
+
+- `index.js`
+- `edit.js`
+- `block.json`
+- `render.php`
+
+However, you can override any of these files by simply placing specially named files alongside the corresponding `.html` source file.
+
+**To override a file, create a new file with the following format:**
+
+```txt
+[block-slug].[filename].[extension]
+```
+
+For example, if you have a block defined in `blocks/hero.html`, you can override its generated `render.php` file by creating:
+
+```txt
+blocks/hero.render.php
+```
+
+Similarly, you can override:
+
+```txt
+blocks/hero.index.js
+blocks/hero.edit.js
+blocks/hero.block.json
+```
+
+These files will be copied **as-is** into the block's output folder and will not be overwritten by the generator.
+
+In the future, you’ll also be able to use this override system to provide editor and frontend specific styles and scripts.
+These features are not implemented yet, but this flexible naming convention is designed to support them seamlessly.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jverneaut/html-to-gutenberg",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "main": "index.js",
   "repository": {
     "type": "git",

src/HTMLToGutenberg.js

@@ -68,8 +68,6 @@ class HTMLToGutenberg {
 
     try {
       for (const HTMLFile of this.HTMLFiles) {
-        const files = [];
-
         const HTMLFileContent = fs.readFileSync(HTMLFile, "utf-8");
 
         const blockData = await getBlockData(HTMLFileContent, {
@@ -89,14 +87,30 @@ class HTMLToGutenberg {
           printRenderPHP(blockData),
         ]);
 
-        files.push({ type: "index", content: indexJS });
-        files.push({ type: "edit", content: editJS });
-        files.push({ type: "json", content: blockJSON });
-        files.push({ type: "php", content: renderPHP });
+        const blockPath = this.generateBlockPath(HTMLFile);
+
+        generatedFiles.push({
+          filename: "index.js",
+          content: indexJS,
+          blockPath,
+        });
+
+        generatedFiles.push({
+          filename: "edit.js",
+          content: editJS,
+          blockPath,
+        });
+
+        generatedFiles.push({
+          filename: "block.json",
+          content: blockJSON,
+          blockPath,
+        });
 
         generatedFiles.push({
-          source: HTMLFile,
-          files,
+          filename: "render.php",
+          content: renderPHP,
+          blockPath,
         });
       }
     } catch (err) {
@@ -106,55 +120,81 @@ class HTMLToGutenberg {
     return generatedFiles;
   }
 
+  async getFilesOverrides() {
+    const overrides = [];
+
+    const htmlFiles = this.HTMLFiles.map((htmlPath) => ({
+      fullPath: path.resolve(htmlPath),
+      baseName: path.basename(htmlPath, ".html"),
+      dir: path.dirname(htmlPath),
+    }));
+
+    const htmlFilesMap = new Map();
+    for (const { baseName, dir } of htmlFiles) {
+      htmlFilesMap.set(path.join(dir, baseName), true);
+    }
+
+    const allFiles = glob.sync(path.join(this.inputDirectory, "/**/*.*"));
+
+    for (const file of allFiles) {
+      const resolved = path.resolve(file);
+
+      if (resolved.endsWith(".html")) continue;
+
+      const filename = path.basename(file);
+      const dirname = path.dirname(file);
+
+      const match = filename.match(/^(.+?)\.(.+?)\.(.+)$/);
+      if (!match) continue;
+
+      const [_, blockSlug, innerName, ext] = match;
+      const htmlFileKey = path.join(dirname, blockSlug);
+
+      if (!htmlFilesMap.has(htmlFileKey)) continue;
+
+      const blockPath = path.join(this.outputDirectory, blockSlug);
+      const content = fs.readFileSync(resolved, "utf-8");
+
+      overrides.push({
+        filename: `${innerName}.${ext}`,
+        content,
+        blockPath,
+      });
+    }
+
+    return overrides;
+  }
+
   createDirectoryIfNotExists(directoryPath) {
     try {
       fs.mkdirSync(directoryPath, { recursive: true });
     } catch {}
   }
 
-  writeFiles(generatedFiles) {
-    const generatedBlocksPaths = [];
+  cleanDirectory(directoryPath) {
+    const filesInDirectory = fs.readdirSync(directoryPath);
 
-    generatedFiles.forEach((generatedFile) => {
-      const blockPath = this.generateBlockPath(generatedFile.source);
-      this.createDirectoryIfNotExists(blockPath);
+    for (const file of filesInDirectory) {
+      if (!["block.json", "edit.js", "index.js", "render.php"].includes(file)) {
+        fs.unlinkSync(path.join(directoryPath, file), (err) => {
+          if (err) throw err;
+        });
+      }
+    }
+  }
 
-      generatedBlocksPaths.push(blockPath);
-
-      generatedFile.files.forEach(({ type, content }) => {
-        switch (type) {
-          case "index":
-            fs.writeFileSync(
-              path.join(blockPath, "index.js"),
-              content,
-              "utf-8",
-            );
-            break;
-
-          case "edit":
-            fs.writeFileSync(path.join(blockPath, "edit.js"), content, "utf-8");
-            break;
-
-          case "json":
-            fs.writeFileSync(
-              path.join(blockPath, "block.json"),
-              content,
-              "utf-8",
-            );
-            break;
-
-          case "php":
-            fs.writeFileSync(
-              path.join(blockPath, "render.php"),
-              content,
-              "utf-8",
-            );
-            break;
-        }
-      });
+  cleanOutputAndWriteFiles(files) {
+    const blockPaths = new Set(files.map((file) => file.blockPath));
+
+    blockPaths.forEach((blockPath) => {
+      this.createDirectoryIfNotExists(blockPath);
+      this.cleanDirectory(blockPath);
     });
 
-    return generatedBlocksPaths;
+    files.forEach((file) => {
+      const { blockPath, filename, content } = file;
+      fs.writeFileSync(path.join(blockPath, filename), content, "utf-8");
+    });
   }
 
   removeDeletedBlocks() {

src/HTMLToGutenbergPlugin.js

@@ -53,7 +53,12 @@ class HTMLToGutenbergPlugin {
 
   async generateAndWriteFiles() {
     const generatedFiles = await this.htmlToGutenberg.generateFiles();
-    this.htmlToGutenberg.writeFiles(generatedFiles);
+    const filesOverrides = await this.htmlToGutenberg.getFilesOverrides();
+
+    this.htmlToGutenberg.cleanOutputAndWriteFiles([
+      ...generatedFiles,
+      ...filesOverrides,
+    ]);
   }
 }