Merge pull request #368 from Krakazybik/feature-docusarus-og-plugin

PROMO-251: OpenGraph dynamic image plugin prototype.

Author: azinit

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,37 @@
+const fs = require("fs");
+const { object, string, number, array, is } = require("superstruct");
+const { objectFromBuffer } = 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;
+}
+
+const Rule = object({
+    name: string(),
+    priority: number(),
+    pattern: string(),
+});
+
+const Config = object({
+    outputDir: string(),
+    textWidthLimit: number(),
+    quality: number(),
+    rules: array(Rule),
+});
+
+function validateConfig(config) {
+    if (is(config, Config)) {
+        return config.rules.reduce((validationResult, rule) => {
+            if (!is(rule, Rule)) return false;
+            return validationResult;
+        }, true);
+    }
+    return false;
+}
+
+module.exports = { getConfig };

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

@@ -0,0 +1,34 @@
+const textToSVG = require("text-to-svg");
+
+function createFontsMapFromTemplates(templates) {
+    const fonts = new Map();
+    templates.forEach((template) => {
+        if (!fonts.has(template.params.font)) {
+            fonts.set(
+                template.params.font,
+                textToSVG.loadSync(`${template.path}\\${template.name}\\${template.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 font width more than widthLimit => scale font width to ~90% of widthLimit */
+    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,29 @@
+const sharp = require("sharp");
+
+function getTemplateImageId(template) {
+    return `${template.name}_${template.params.image}`;
+}
+
+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((template) => {
+        const imageId = getTemplateImageId(template);
+
+        if (!images.has(imageId)) {
+            images.set(imageId, createImageFromTemplate(template));
+        }
+    });
+    return images;
+}
+
+module.exports = { createImagesMapFromTemplates, getTemplateImageId };

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

@@ -0,0 +1,100 @@
+const fs = require("fs");
+const sha1 = require("sha1");
+const { getTemplates } = require("./template");
+const { createLayoutLayers } = require("./layout");
+const { createFontsMapFromTemplates } = require("./font");
+const { createImagesMapFromTemplates, getTemplateImageId } = require("./image");
+const { getConfig } = require("./config");
+const { getTemplateNameByRules } = require("./rules");
+
+module.exports = function ({ templatesDir }) {
+    const initData = bootstrap(templatesDir);
+    if (!initData) {
+        console.error("OpenGraph plugin exit with error.");
+        return;
+    }
+
+    const { config } = initData;
+
+    return {
+        name: "docusaurus-plugin-open-graph-image",
+        async postBuild({ plugins, outDir, i18n }) {
+            const docsPlugin = plugins.find(
+                (plugin) => plugin.name === "docusaurus-plugin-content-docs",
+            );
+
+            if (!docsPlugin) throw new Error("Docusaurus Doc plugin not found.");
+
+            const previewOutputDir = `${outDir}\\${config.outputDir}`;
+            fs.mkdir(previewOutputDir, { recursive: true }, (error) => {
+                if (error) throw error;
+            });
+
+            const docsContent = docsPlugin.content;
+            const docsVersions = docsContent.loadedVersions;
+            docsVersions.forEach((version) => {
+                const { docs } = version;
+
+                docs.forEach((document) => {
+                    generateImageFromDoc(initData, document, i18n.currentLocale, previewOutputDir);
+                });
+            });
+        },
+    };
+};
+
+function bootstrap(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) return;
+
+    const config = getConfig(templatesDir);
+    if (!config) return;
+
+    // TODO: File not found exception?
+    const fonts = createFontsMapFromTemplates(templates);
+    const images = createImagesMapFromTemplates(templates);
+
+    return { templates, config, fonts, images };
+}
+
+async function generateImageFromDoc(initData, doc, locale, outputDir) {
+    const { templates, config, images, fonts } = initData;
+    const { id, title } = doc;
+
+    const hashFileName = sha1(id + locale);
+
+    const templateName = getTemplateNameByRules(id, config.rules);
+
+    const template = templates.find((template) => template.name === templateName);
+
+    const previewImage = await images.get(getTemplateImageId(template)).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);
+    }
+}

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

@@ -0,0 +1,27 @@
+const { createSVGText } = require("./font");
+
+function createLayoutLayers(doc, layout, previewFont, textWidthLimit) {
+    /* Check for all layers names exist in doc fields */
+    if (layout.some((layer) => !doc[layer.name])) {
+        console.error(`Wrong template config.`);
+        return;
+    }
+
+    return layout.map((layer) => {
+        const layoutOptions = {
+            fontSize: layer.fontSize,
+            fill: layer.fill,
+            stroke: layer.stroke,
+        };
+
+        return {
+            input: Buffer.from(
+                createSVGText(previewFont, doc[layer.name], layoutOptions, textWidthLimit),
+            ),
+            top: layer.top,
+            left: layer.left,
+        };
+    });
+}
+
+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 };

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

@@ -0,0 +1,59 @@
+const fs = require("fs");
+const { object, string, number, array, is } = require("superstruct");
+const { objectFromBuffer } = require("./utils");
+
+const dirIgnore = ["config.json"];
+
+function getTemplates(templatesDir, encode = "utf8") {
+    const templatesDirNames = fs
+        .readdirSync(templatesDir)
+        .filter((fileName) => !dirIgnore.includes(fileName));
+
+    // TODO: check file exist
+    const templates = templatesDirNames.map((templateName) => ({
+        name: templateName,
+        path: templatesDir,
+        params: objectFromBuffer(
+            fs.readFileSync(`${templatesDir}\\${templateName}\\template.json`, encode),
+        ),
+    }));
+
+    if (!templates.some(validateTemplate)) {
+        console.error("Templates validation error.");
+        return;
+    }
+
+    return templates;
+}
+
+// TODO: May be with postEffects, images and etc? (optional fontSize, fill and etc)
+const Layout = object({
+    type: string(),
+    name: string(),
+    fontSize: number(),
+    fill: string(),
+    stroke: string(),
+    top: number(),
+    left: number(),
+});
+
+const Template = object({
+    image: string(),
+    font: string(),
+    layout: array(Layout),
+});
+
+function validateTemplate({ params }) {
+    if (is(params, Template)) {
+        if (params.layout.length === 0) return false;
+
+        return params.layout.reduce((validationResult, layout) => {
+            if (!is(layout, Layout)) return false;
+            return validationResult;
+        }, true);
+    }
+
+    return false;
+}
+
+module.exports = { getTemplates };