PROMO-251: OpenGraph dynamic image plugin prototype.

website/.eslintrc.js

@@ -23,6 +23,12 @@ module.exports = {
             },
         ],
         "linebreak-style": [2, "unix"],
+        "import/no-unresolved": [
+            "error",
+            {
+                ignore: ["^@theme-original"],
+            },
+        ],
     },
     settings: {
         "import/resolver": {

website/docusaurus.config.js

@@ -1,4 +1,5 @@
 require("dotenv").config();
+const path = require("path");
 const { REDIRECTS, SECTIONS, LEGACY_ROUTES } = require("./routes.config");
 
 const DOMAIN = "https://feature-sliced.design/";
@@ -254,6 +255,12 @@ const plugins = [
         },
     ],
     process.env.HOTJAR_ID && "docusaurus-plugin-hotjar", // For preventing crashing
+    [
+        path.resolve(__dirname, "./plugins/docusaurus-plugin-open-graph-image"),
+        {
+            templatesDir: path.resolve(__dirname, "open-graph-templates"),
+        },
+    ],
 ].filter(Boolean);
 
 /** @type {Config["themeConfig"]["algolia"]} */

website/open-graph-templates/basic/template.json

@@ -0,0 +1,15 @@
+{
+  "image": "preview.png",
+  "font": "arial.ttf",
+  "layout": [
+    {
+      "type": "text",
+      "name": "title",
+      "fontSize": 80,
+      "fill": "white",
+      "stroke": "white",
+      "top": 400,
+      "left": 200
+    }
+  ]
+}

website/open-graph-templates/config.json

@@ -0,0 +1,22 @@
+{
+  "outputDir": "assets/og",
+  "textWidthLimit": 1100,
+  "quality": 70,
+  "rules": [
+    {
+      "name": "basic",
+      "priority": 0,
+      "pattern": "."
+    },
+    {
+      "name": "gray",
+      "priority": 1,
+      "pattern": "^concepts*"
+    },
+    {
+      "name": "gray",
+      "priority": 2,
+      "pattern": "^about*"
+    }
+  ]
+}

website/open-graph-templates/gray/template.json

@@ -0,0 +1,15 @@
+{
+  "image": "preview.png",
+  "font": "Kanit-bold.ttf",
+  "layout": [
+    {
+      "type": "text",
+      "name": "title",
+      "fontSize": 80,
+      "fill": "white",
+      "stroke": "white",
+      "top": 200,
+      "left": 200
+    }
+  ]
+}

website/package.json

@@ -36,6 +36,10 @@
         "react": "^17.0.1",
         "react-cookie-consent": "^6.4.1",
         "react-dom": "^17.0.1",
+        "sha1": "^1.1.1",
+        "sharp": "^0.29.3",
+        "superstruct": "^0.15.3",
+        "text-to-svg": "^3.1.5",
         "url-loader": "^4.1.1"
     },
     "browserslist": {

website/plugins/docusaurus-plugin-open-graph-image/Readme.md

@@ -0,0 +1,86 @@
+# Docusaurus OpenGraph image generator plugin
+Как это работает?
+Для манипуляций с изображениями используется [sharp](https://sharp.pixelplumbing.com/) работающий через `libvips`. На этапе postBuild, когда у нас всё собрано, получаем инфу из doc плагина и на её основе генерируем изображение с необходимыми нам дополнительными слоями. Сами изображения и слои описываем в наших шаблонах. Если нам нужно применить конкретный шаблон для конкретного документа - используем правила.
+
+## Usage
+Шаблоны помещаются в папку `open-graph-templates`. Для настройки плагина используется `config.json`.  
+Шаблонов может быть сколько угодно много, но при этом (Важно!) `basic` обязательный для работы плагина.
+
+
+### Templates folder files listing.
+```sh
+└── website/
+    └── open-graph-tempaltes/ 
+        # required
+        ├── basic
+        |     ├── font.ttf
+        |     ├── preview.png
+        |     └── template.json
+        |
+        └── config.json
+```
+
+### Templates configuration file example:  
+**config.json**
+```json
+{
+  "outputDir": "assets/og",
+  "textWidthLimit": 1100,
+  "quality": 70,
+  "rules": [
+    {
+      "name": "basic",
+      "priority": 0,
+      "pattern": "."
+    },
+    {
+      "name": "gray",
+      "priority": 1,
+      "pattern": "^concepts*"
+    },
+    {
+      "name": "gray",
+      "priority": 2,
+      "pattern": "^about*"
+    }
+  ]
+}
+
+```
+`outputDir` - выходная директория в билде для наших картинок.  
+`textWidthLimit` - ограничение по длине текстовой строки, при превышении которого шрифт будет скейлиться.  
+`quality` - качество(компрессия JPEG Quality) картинки на выходе.
+`rules` - правила(их может быть сколько угодно много), по которым будет применяться тот или иной шаблон в зависимости от пути до документа(позволяет нам для разных эндпоинтов док, создавать свои превьюшки):
+- `rules.name` - имя шаблона (название папки в open-graph-templates)
+- `rules.priority` - приоритет, правило с более высоким приоритетом замещает собой правила с более низким.
+- `rules.pattern` - RegExp шаблон, по которому сравнивается путь документа для применения того или иного правила.  
+
+
+### Template configuration example:  
+**template.json**
+```json
+{
+  "image": "preview.png",
+  "font": "arial.ttf",
+  "layout": [
+    {
+      "type": "text",
+      "name": "title",
+      "fontSize": 80,
+      "fill": "white",
+      "stroke": "white",
+      "top": 400,
+      "left": 200
+    }
+  ]
+}
+```
+`image` - путь до изображения на основе которого шаблон будет делать preview.  
+`font` - используемый файл шрифта.  
+`layout` - описывает накладываемые слои и их расположение:  
+- `layout.type` - задел на будущее пока только "text", в дальнейшем планируется image, postEffect и тд.
+- `layout.name` - на данный момент для text типа получает поле из плагина doc, полезные варианты: title, description, formattedLastUpdatedAt остальные поля очень спорны для применения.
+- `layout.fontSize` - размер шрифта для слоя с типом text.
+- `layout.fill` - цвет заливки букв для слоя с типом text.
+- `layout.stroke` - цвет контура букв для слоя с типом text.
+- `layout.top`, `layout.left` - отступ нашего слоя от края изображения.

website/plugins/docusaurus-plugin-open-graph-image/config.js

@@ -0,0 +1,12 @@
+const fs = require("fs");
+const { objectFromBuffer, validateConfig } = require("./utils");
+
+function getConfig(path, encode = "utf-8") {
+    const config = objectFromBuffer(fs.readFileSync(`${path}\\config.json`, encode));
+    if (!validateConfig(config)) {
+        console.error("Config validation error");
+        return;
+    }
+    return config;
+}
+module.exports = { getConfig };

website/plugins/docusaurus-plugin-open-graph-image/font.js

@@ -0,0 +1,33 @@
+const textToSVG = require("text-to-svg");
+
+function createFontsMapFromTemplates(templates) {
+    const fonts = new Map();
+    templates.forEach((item) => {
+        if (!fonts.has(item.params.font)) {
+            fonts.set(
+                item.params.font,
+                textToSVG.loadSync(`${item.path}\\${item.name}\\${item.params.font}`),
+            );
+        }
+    });
+    return fonts;
+}
+
+function createSVGText(
+    font,
+    text,
+    { fontSize = 72, fill = "white", stroke = "white" },
+    widthLimit = 1000,
+) {
+    const attributes = { fill, stroke };
+    const options = { fontSize, anchor: "top", attributes };
+
+    if (widthLimit) {
+        const { width } = font.getMetrics(text, options);
+        if (width > widthLimit)
+            options.fontSize = Math.trunc((fontSize * 0.9) / (width / widthLimit));
+    }
+
+    return font.getSVG(text, options);
+}
+module.exports = { createSVGText, createFontsMapFromTemplates };

website/plugins/docusaurus-plugin-open-graph-image/image.js

@@ -0,0 +1,23 @@
+const sharp = require("sharp");
+
+function createImagePipeline(file) {
+    // TODO: Apply effects, compression and etc.
+    // TODO: File validation?
+    return sharp(file);
+}
+
+function createImageFromTemplate({ path, name, params }) {
+    return createImagePipeline(`${path}\\${name}\\${params.image}`);
+}
+
+function createImagesMapFromTemplates(templates) {
+    const images = new Map();
+    templates.forEach((item) => {
+        if (!images.has(`${item.name}_${item.params.image}`)) {
+            images.set(`${item.name}_${item.params.image}`, createImageFromTemplate(item));
+        }
+    });
+    return images;
+}
+
+module.exports = { createImagesMapFromTemplates };

website/plugins/docusaurus-plugin-open-graph-image/index.js

@@ -0,0 +1,90 @@
+const fs = require("fs");
+const sha1 = require("sha1");
+const { getTemplates } = require("./template");
+const { validateTemplate } = require("./utils");
+const { createLayoutLayers } = require("./layout");
+const { createFontsMapFromTemplates } = require("./font");
+const { createImagesMapFromTemplates } = require("./image");
+const { getConfig } = require("./config");
+const { getTemplateNameByRules } = require("./rules");
+
+module.exports = function (context, { templatesDir }) {
+    const isProd = process.env.NODE_ENV === "production";
+    if (!isProd) return;
+
+    if (!templatesDir) {
+        console.error("Wrong templatesDir option.");
+        return;
+    }
+
+    const templates = getTemplates(templatesDir);
+    if (!templates.some(validateTemplate)) {
+        return;
+    }
+
+    const config = getConfig(templatesDir);
+    if (!config) return;
+
+    // TODO: File not found exception?
+    const fonts = createFontsMapFromTemplates(templates);
+    const images = createImagesMapFromTemplates(templates);
+
+    async function generateImageFromDoc(doc, locale, outputDir) {
+        const { id, title } = doc;
+
+        const hashFileName = sha1(id + locale);
+
+        const templateName = getTemplateNameByRules(id, config.rules);
+
+        const template = templates.find((item) => item.name === templateName);
+
+        const previewImage = await images.get(`${template.name}_${template.params.image}`).clone();
+
+        const previewFont = fonts.get(template.params.font);
+
+        const textLayers = createLayoutLayers(
+            doc,
+            template.params.layout,
+            previewFont,
+            config.textWidthLimit,
+        );
+
+        try {
+            await previewImage.composite(textLayers);
+            await previewImage
+                .jpeg({
+                    quality: config.quality,
+                    chromaSubsampling: "4:4:4",
+                })
+                .toFile(`${outputDir}\\${hashFileName}.jpg`);
+        } catch (error) {
+            console.error(error, id, title, hashFileName);
+        }
+    }
+
+    return {
+        name: "docusaurus-plugin-open-graph-image",
+        async postBuild({ plugins, outDir, i18n }) {
+            const docsPlugin = plugins.find(
+                (plugin) => plugin.name === "docusaurus-plugin-content-docs",
+            );
+
+            const previewOutputDir = `${outDir}\\${config.outputDir}`;
+            fs.mkdir(previewOutputDir, { recursive: true }, (error) => {
+                if (error) throw error;
+            });
+
+            if (docsPlugin) {
+                const docsContent = docsPlugin.content;
+                const docsVersions = docsContent.loadedVersions;
+                docsVersions.forEach((version) => {
+                    const { docs } = version;
+
+                    docs.forEach((item) => {
+                        generateImageFromDoc(item, i18n.currentLocale, previewOutputDir);
+                    });
+                });
+            }
+        },
+    };
+};

website/plugins/docusaurus-plugin-open-graph-image/layout.js

@@ -0,0 +1,30 @@
+const { createSVGText } = require("./font");
+
+function createLayoutLayers(doc, layout, previewFont, textWidthLimit) {
+    const layers = layout.map((item) => {
+        if (!Object.prototype.hasOwnProperty.call(doc, item.name)) {
+            console.error(`Wrong template config? Doc property ${item.name} not found.`);
+            return undefined;
+        }
+
+        const layoutOptions = {
+            fontSize: item.fontSize,
+            fill: item.fill,
+            stroke: item.stroke,
+        };
+
+        return {
+            input: Buffer.from(
+                createSVGText(previewFont, doc[item.name], layoutOptions, textWidthLimit),
+            ),
+            top: item.top,
+            left: item.left,
+        };
+    });
+
+    if (layers.includes(undefined)) return;
+
+    return layers;
+}
+
+module.exports = { createLayoutLayers };

website/plugins/docusaurus-plugin-open-graph-image/rules.js

@@ -0,0 +1,7 @@
+function getTemplateNameByRules(path, rules) {
+    const filteredRules = rules.filter((rule) => new RegExp(rule.pattern).test(path));
+    const sortedRules = filteredRules.sort((a, b) => b.priority - a.priority);
+    return sortedRules[0]?.name || "basic";
+}
+
+module.exports = { getTemplateNameByRules };